Memory Slices
Eina » Data Types

These functions provide memory slices in read-only and read-write forms. More...

## Data Structures

struct | _Eina_Slice
| Defines a read-only memory region. More...
struct | _Eina_Rw_Slice
| Defines a read-and-write able memory region. More...

## Macros

#define | EINA_SLICE_ARRAY(buf)
| Initializer for arrays of any kind.
#define | EINA_RW_SLICE_DECLARE(name, length)
| Declare a local (stack) array for storage at given length and initialize an Eina_Rw_Slice called name.
#define | EINA_SLICE_STR_LITERAL(buf)
| Initializer for string literals (those declared as double-quoted).
#define | EINA_SLICE_STR(str)
| Initializer for strings (uses strlen()).
#define | EINA_SLICE_STR_FULL(str)
| Same as EINA_SLICE_STR_FULL, but it also contains the \0 element of the string.
#define | EINA_SLICE_STR_FMT "%.*s"
| To be used in printf()-like statements, prints the slice as a string, its `len` is to be used, then it doesn't need the null terminator.
#define | EINA_SLICE_STR_PRINT(s)
| To be used in printf()-like statements when EINA_SLICE_STR_FMT was used, it will print the slice as a string up to `len`.
#define | EINA_SLICE_FMT "%p+%zu"
| To be used in printf()-like statements, prints the slice as `0x1234+12` (`mem` + `len`).
#define | EINA_SLICE_PRINT(s)
| To be used in printf()-like statements when EINA_SLICE_FMT was used, it will print the slice `mem` and `len`.
#define | EINA_SLICE_FOREACH(s, itr)
| Iterate over the slice memory, using `itr`.

## Typedefs

typedef struct _Eina_Slice | Eina_Slice
| Defines a read-only memory region.
typedef struct _Eina_Rw_Slice | Eina_Rw_Slice
| Defines a read-and-write able memory region.

## Functions

static Eina_Slice | eina_rw_slice_slice_get (const Eina_Rw_Slice rw_slice)
| Convert the Read-write slice to read-only.
static Eina_Rw_Slice | eina_slice_dup (const Eina_Slice slice)
| Creates a duplicate of slice's memory.
static Eina_Rw_Slice | eina_rw_slice_dup (const Eina_Rw_Slice rw_slice)
| Creates a duplicate of slice's memory.
static int | eina_slice_compare (const Eina_Slice a, const Eina_Slice b)
| Compare two slices, similar to memcmp().
static int | eina_rw_slice_compare (const Eina_Rw_Slice a, const Eina_Rw_Slice b)
| Compare two slices, similar to memcmp().
static Eina_Rw_Slice | eina_rw_slice_copy (const Eina_Rw_Slice dest, const Eina_Slice src)
| Copy a read-only slice to a read-write one, similar to memcpy().
static Eina_Slice | eina_slice_seek (const Eina_Slice slice, ssize_t offset, int whence)
| Seek within a slice, similar to fseek().
static Eina_Rw_Slice | eina_rw_slice_seek (const Eina_Rw_Slice rw_slice, ssize_t offset, int whence)
| Seek within a read-write slice, similar to fseek().
static const void * | eina_slice_strchr (const Eina_Slice slice, int c)
| Find a character inside the slice, similar to memchr().
static const void * | eina_slice_find (const Eina_Slice slice, const Eina_Slice needle)
| Find a needle inside the slice, similar to memmem().
static Eina_Bool | eina_slice_startswith (const Eina_Slice slice, const Eina_Slice prefix)
| Checks if the slice starts with a prefix.
static Eina_Bool | eina_slice_endswith (const Eina_Slice slice, const Eina_Slice suffix)
| Checks if the slice ends with a suffix.
static void * | eina_rw_slice_strchr (const Eina_Rw_Slice rw_slice, int c)
| Find a character inside the slice, similar to memchr().
static void * | eina_rw_slice_find (const Eina_Rw_Slice rw_slice, const Eina_Slice needle)
| Find a needle inside the slice, similar to memmem().
static Eina_Bool | eina_rw_slice_startswith (const Eina_Rw_Slice slice, const Eina_Slice prefix)
| Checks if the slice starts with a prefix.
static Eina_Bool | eina_rw_slice_endswith (const Eina_Rw_Slice slice, const Eina_Slice suffix)
| Checks if the slice ends with a suffix.
static const void * | eina_slice_end_get (const Eina_Slice slice)
| The memory position where the slice ends.
static void * | eina_rw_slice_end_get (const Eina_Rw_Slice rw_slice)
| The memory position where the slice ends.
static char * | eina_slice_strdup (const Eina_Slice slice)
| A null-terminated string for this slice.
static char * | eina_rw_slice_strdup (const Eina_Rw_Slice rw_slice)
| A null-terminated string for this slice.

## Detailed Description

These functions provide memory slices in read-only and read-write forms.

Memory slices define a contiguous linear memory starting at a given pointer (`mem`) and spanning for a given length (`len`).

They may be read-only (Eina_Slice) or read-write (Eina_Rw_Slice).

Since
  1.19

## Macro Definition Documentation

## EINA_SLICE_ARRAY

#define EINA_SLICE_ARRAY | ( |  | buf | ) |

Value:
{.len = ((sizeof(buf) / sizeof((buf)[0])) * sizeof((buf)[0])), .mem = (buf)}

Initializer for arrays of any kind.

Parameters

  [in] | buf | The array to create the slice from.

Returns
  The initialized slice object.

It is often useful for globals.

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

static uint8_t buf[1024];
static Eina_Slice rw_slice = EINA_SLICE_ARRAY(buf);
EINA_SLICE_ARRAY
#define EINA_SLICE_ARRAY(buf)
Initializer for arrays of any kind.
Definition eina_slice.h:396
Eina_Slice
struct _Eina_Slice Eina_Slice
Defines a read-only memory region.
Definition eina_slice.h:70

See also
  EINA_SLICE_STR_LITERAL() for specific version that checks for string literals.

Since
  1.19

## EINA_RW_SLICE_DECLARE

#define EINA_RW_SLICE_DECLARE | ( |  | name,
|  |  | length )

Value:
uint8_t _eina_slice_storage_ ## name [(length)] = { 0 }; \
Eina_Rw_Slice name = EINA_SLICE_ARRAY(_eina_slice_storage_ ## name)
Eina_Rw_Slice
struct _Eina_Rw_Slice Eina_Rw_Slice
Defines a read-and-write able memory region.
Definition eina_slice.h:83

Declare a local (stack) array for storage at given length and initialize an Eina_Rw_Slice called name.

Parameters

  [in] | name | the name of the variable to be the Eina_Rw_Slice.
  [in] | length | the size in bytes of the storage.

Since
  1.19

## EINA_SLICE_STR_LITERAL

#define EINA_SLICE_STR_LITERAL | ( |  | buf | ) |

Value:
{.len = (sizeof("" buf) - 1), .mem = (buf)}

Initializer for string literals (those declared as double-quoted).

The size will NOT include the trailing null-terminator.

It is often useful for globals.

Parameters

  [in] | buf | The array to create the slice from.

Returns
  The initialized slice object.

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

static const Eina_Slice ro_slice = EINA_SLICE_STR_LITERAL("hello world");
EINA_SLICE_STR_LITERAL
#define EINA_SLICE_STR_LITERAL(buf)
Initializer for string literals (those declared as double-quoted).
Definition eina_slice.h:441

See also
  EINA_SLICE_STR() for more generic version.
  EINA_SLICE_ARRAY() for version that uses a general array.

Since
  1.19

## EINA_SLICE_STR

#define EINA_SLICE_STR | ( |  | str | ) |

Value:
{.len = strlen((str)), .mem = (str)}

Initializer for strings (uses strlen()).

Parameters

  [in] | str | The string to create the slice from.

Returns
  The initialized slice object.

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

Eina_Slice ro_slice = EINA_SLICE_STR("hello world");
EINA_SLICE_STR
#define EINA_SLICE_STR(str)
Initializer for strings (uses strlen()).
Definition eina_slice.h:465

See also
  EINA_SLICE_STR() for specific version using literals.

Since
  1.19

## EINA_SLICE_STR_FULL

#define EINA_SLICE_STR_FULL | ( |  | str | ) |

Value:
{.len = strlen((str)) + 1, .mem = (str)}

Same as EINA_SLICE_STR_FULL, but it also contains the \0 element of the string.

Parameters

  [in] | str | The string to create the slice from.

Returns
  The initialized slice object.

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

Eina_Slice ro_slice = EINA_SLICE_STR_FULL("hello world");
EINA_SLICE_STR_FULL
#define EINA_SLICE_STR_FULL(str)
Same as EINA_SLICE_STR_FULL, but it also contains the \0 element of the string.
Definition eina_slice.h:488

See also
  EINA_SLICE_STR_FULL() for specific version using literals.

Since
  1.24

Referenced by elm_drag_start().

## EINA_SLICE_STR_FMT

#define EINA_SLICE_STR_FMT "%.*s"

To be used in printf()-like statements, prints the slice as a string, its `len` is to be used, then it doesn't need the null terminator.

Use with EINA_SLICE_STR_PRINT()

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

Eina_Slice s = EINA_SLICE_STR_LITERAL("hello");
printf("s=" EINA_SLICE_STR_FMT "\n", EINA_SLICE_STR_PRINT(s));
EINA_SLICE_STR_PRINT
#define EINA_SLICE_STR_PRINT(s)
To be used in printf()-like statements when EINA_SLICE_STR_FMT was used, it will print the slice as a...
Definition eina_slice.h:532
EINA_SLICE_STR_FMT
#define EINA_SLICE_STR_FMT
To be used in printf()-like statements, prints the slice as a string, its len is to be used,...
Definition eina_slice.h:510

Since
  1.19

## EINA_SLICE_STR_PRINT

#define EINA_SLICE_STR_PRINT | ( |  | s | ) |

Value:
(int)(s).len, (const char *)(s).mem

To be used in printf()-like statements when EINA_SLICE_STR_FMT was used, it will print the slice as a string up to `len`.

Parameters

  [in] | s | The slice.

Returns
  The arguments for an EINA_SLICE_STR_FMT formatted printf.

Use with EINA_SLICE_STR_FMT.

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

Eina_Slice s = EINA_SLICE_STR_LITERAL("hello");
printf("s=" EINA_SLICE_STR_FMT "\n", EINA_SLICE_STR_PRINT(s));

Since
  1.19

## EINA_SLICE_FMT

#define EINA_SLICE_FMT "%p+%zu"

To be used in printf()-like statements, prints the slice as `0x1234+12` (`mem` + `len`).

Use with EINA_SLICE_PRINT()

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

Eina_Slice s = EINA_SLICE_STR_LITERAL("hello");
printf("s=" EINA_SLICE_FMT "\n", EINA_SLICE_PRINT(s));
EINA_SLICE_PRINT
#define EINA_SLICE_PRINT(s)
To be used in printf()-like statements when EINA_SLICE_FMT was used, it will print the slice mem and ...
Definition eina_slice.h:573
EINA_SLICE_FMT
#define EINA_SLICE_FMT
To be used in printf()-like statements, prints the slice as 0x1234+12 (mem + len).
Definition eina_slice.h:551

Since
  1.19

## EINA_SLICE_PRINT

#define EINA_SLICE_PRINT | ( |  | s | ) |

Value:
(s).mem, (s).len

To be used in printf()-like statements when EINA_SLICE_FMT was used, it will print the slice `mem` and `len`.

Use with EINA_SLICE_FMT.

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.

Parameters

  [in] | s | The slice.

Returns
  The arguments for an EINA_SLICE_FMT formatted printf.

Eina_Slice s = EINA_SLICE_STR_LITERAL("hello");
printf("s=" EINA_SLICE_FMT "\n", EINA_SLICE_PRINT(s));

Since
  1.19

## EINA_SLICE_FOREACH

#define EINA_SLICE_FOREACH | ( |  | s,
|  |  | itr )

Value:
for ((itr) = (s).mem; \
(void *)(itr) < (void *)((s).bytes + (s).len); \
(itr)++)

Iterate over the slice memory, using `itr`.

Each increment will be using the size of `itr` pointer (int32_t* will do in increments of 4 bytes).

Note
  This macro is usable with both Eina_Slice or Eina_Rw_Slice.
  Be aware of memory alignment! Accessing unaligned memory may not be supported in some architectures.

Parameters

  [in] | s | The slice.
  [in,out] | itr | the iterator to hold each byte. Use a proper type, not "void*" or "const void*" as it doesn't have an intrinsic size.

Since
  1.19

## Typedef Documentation

## Eina_Slice

typedef struct _Eina_Slice Eina_Slice

Defines a read-only memory region.

The slice is a memory starting at `mem` and accessible up to `len` bytes.

See also
  Eina_Rw_Slice for read-write memory regions.

Since
  1.19

## Eina_Rw_Slice

typedef struct _Eina_Rw_Slice Eina_Rw_Slice

Defines a read-and-write able memory region.

The slice is a memory starting at `mem` and accessible up to `len` bytes.

See also
  Eina_Slice for read-only memory regions.

Since
  1.19

## Function Documentation

## eina_rw_slice_slice_get()

Eina_Slice eina_rw_slice_slice_get | ( | const Eina_Rw_Slice | rw_slice | ) |

inline static

Convert the Read-write slice to read-only.

Parameters

  [in] | rw_slice | the read-write slice to convert.

Returns
  the red-only slice matching the slice.

## eina_slice_dup()

Eina_Rw_Slice eina_slice_dup | ( | const Eina_Slice | slice | ) |

inline static

Creates a duplicate of slice's memory.

Parameters

  [in] | slice | the input to duplicate

Returns
  a new read-write slice with new `mem` that matches slice contents. The new `mem` is allocated with malloc() and must be released with free().

See also
  eina_rw_slice_copy()
  eina_rw_slice_dup()

Since
  1.19

References EINA_WARN_UNUSED_RESULT.

## eina_rw_slice_dup()

Eina_Rw_Slice eina_rw_slice_dup | ( | const Eina_Rw_Slice | rw_slice | ) |

inline static

Creates a duplicate of slice's memory.

Parameters

  [in] | rw_slice | the input to duplicate

Returns
  a new read-write slice with new `mem` that matches slice contents. The new `mem` is allocated with malloc() and must be released with free().

See also
  eina_rw_slice_copy()
  eina_slice_dup()

Since
  1.19

References EINA_WARN_UNUSED_RESULT.

## eina_slice_compare()

int eina_slice_compare | ( | const Eina_Slice | a,
|  | const Eina_Slice | b )

inline static

Compare two slices, similar to memcmp().

Parameters

  [in] | a | the first slice to compare.
  [in] | b | the second slice to compare.

Returns
  0 if equal, < 0 if a < b, > 0 if a > b

Since
  1.19

## eina_rw_slice_compare()

int eina_rw_slice_compare | ( | const Eina_Rw_Slice | a,
|  | const Eina_Rw_Slice | b )

inline static

Compare two slices, similar to memcmp().

Parameters

  [in] | a | the first slice to compare.
  [in] | b | the second slice to compare.

Returns
  0 if equal, < 0 if a < b, > 0 if a > b

Since
  1.19

## eina_rw_slice_copy()

Eina_Rw_Slice eina_rw_slice_copy | ( | const Eina_Rw_Slice | dest,
|  | const Eina_Slice | src )

inline static

Copy a read-only slice to a read-write one, similar to memcpy().

Parameters

  [in] | dest | where to write the memory.
  [in] | src | where to load memory.

Returns
  a new slice with the resulting write. Note that the length (`len`) will be the smallest of dest and src.

See also
  eina_rw_slice_dup()
  eina_slice_dup()

Since
  1.19

## eina_slice_seek()

Eina_Slice eina_slice_seek | ( | const Eina_Slice | slice,
|  | ssize_t | offset,
|  | int | whence )

inline static

Seek within a slice, similar to fseek().

Parameters

  [in] | slice | the containing slice to seek inside.
  [in] | offset | how to get to the new position.
  [in] | whence | SEEK_SET, SEEK_END as fseek().

Returns
  a new slice contained inside, it will start at the given offset and have a length that goes until the end of the slice. If an invalid whence, a zero-sized slice starting at slice mem will be returned. The slice is guaranteed to be contained within slice, even if offset causes it to go out of bounds, then it will be clamped to 0 and slice.len.

Since
  1.19

## eina_rw_slice_seek()

Eina_Rw_Slice eina_rw_slice_seek | ( | const Eina_Rw_Slice | rw_slice,
|  | ssize_t | offset,
|  | int | whence )

inline static

Seek within a read-write slice, similar to fseek().

Parameters

  [in] | rw_slice | the containing slice to seek inside.
  [in] | offset | how to get to the new position.
  [in] | whence | SEEK_SET, SEEK_END as fseek().

Returns
  a new slice contained inside, it will start at the given offset and have a length that goes until the end of the rw_slice. If an invalid whence, a zero-sized slice starting at rw_slice mem will be returned. The slice is guaranteed to be contained within rw_slice, even if offset causes it to go out of bounds, then it will be clamped to 0 and slice.len.

Since
  1.19

## eina_slice_strchr()

const void * eina_slice_strchr | ( | const Eina_Slice | slice,
|  | int | c )

inline static

Find a character inside the slice, similar to memchr().

Parameters

  [in] | slice | the reference memory.
  [in] | c | the byte (character) to find.

Returns
  the memory within slice or `NULL` if not found.

Since
  1.19

## eina_slice_find()

const void * eina_slice_find | ( | const Eina_Slice | slice,
|  | const Eina_Slice | needle )

inline static

Find a needle inside the slice, similar to memmem().

Parameters

  [in] | slice | the reference memory.
  [in] | needle | what to find.

Returns
  the memory within slice or `NULL` if not found.

Since
  1.19

## eina_slice_startswith()

Eina_Bool eina_slice_startswith | ( | const Eina_Slice | slice,
|  | const Eina_Slice | prefix )

inline static

Checks if the slice starts with a prefix.

Parameters

  [in] | slice | the reference memory.
  [in] | prefix | the slice to check if slice starts with.

Returns
  EINA_TRUE if slice starts with prefix, EINA_FALSE otherwise.

Since
  1.19

## eina_slice_endswith()

Eina_Bool eina_slice_endswith | ( | const Eina_Slice | slice,
|  | const Eina_Slice | suffix )

inline static

Checks if the slice ends with a suffix.

Parameters

  [in] | slice | the reference memory.
  [in] | suffix | the slice to check if slice ends with.

Returns
  EINA_TRUE if slice ends with suffix, EINA_FALSE otherwise.

Since
  1.19

## eina_rw_slice_strchr()

void * eina_rw_slice_strchr | ( | const Eina_Rw_Slice | rw_slice,
|  | int | c )

inline static

Find a character inside the slice, similar to memchr().

Parameters

  [in] | rw_slice | the reference memory.
  [in] | c | the byte (character) to find.

Returns
  the memory within slice or `NULL` if not found.

Since
  1.19

## eina_rw_slice_find()

void * eina_rw_slice_find | ( | const Eina_Rw_Slice | rw_slice,
|  | const Eina_Slice | needle )

inline static

Find a needle inside the slice, similar to memmem().

Parameters

  [in] | rw_slice | the reference memory.
  [in] | needle | what to find.

Returns
  the memory within slice or `NULL` if not found.

Since
  1.19

## eina_rw_slice_startswith()

Eina_Bool eina_rw_slice_startswith | ( | const Eina_Rw_Slice | slice,
|  | const Eina_Slice | prefix )

inline static

Checks if the slice starts with a prefix.

Parameters

  [in] | slice | the reference memory.
  [in] | prefix | the slice to check if slice starts with.

Returns
  EINA_TRUE if slice starts with prefix, EINA_FALSE otherwise.

Since
  1.19

## eina_rw_slice_endswith()

Eina_Bool eina_rw_slice_endswith | ( | const Eina_Rw_Slice | slice,
|  | const Eina_Slice | suffix )

inline static

Checks if the slice ends with a suffix.

Parameters

  [in] | slice | the reference memory.
  [in] | suffix | the slice to check if slice ends with.

Returns
  EINA_TRUE if slice ends with suffix, EINA_FALSE otherwise.

Since
  1.19

## eina_slice_end_get()

const void * eina_slice_end_get | ( | const Eina_Slice | slice | ) |

inline static

The memory position where the slice ends.

Note
  this is out-of the slice, the first byte after it ends and must not be accessed.

Parameters

  [in] | slice | the reference memory.

Returns
  the first byte after the slice ends.

Since
  1.19

## eina_rw_slice_end_get()

void * eina_rw_slice_end_get | ( | const Eina_Rw_Slice | rw_slice | ) |

inline static

The memory position where the slice ends.

Note
  this is out-of the slice, the first byte after it ends and must not be accessed.

Parameters

  [in] | rw_slice | the reference memory.

Returns
  the first byte after the slice ends.

Since
  1.19

## eina_slice_strdup()

char * eina_slice_strdup | ( | const Eina_Slice | slice | ) |

inline static

A null-terminated string for this slice.

Parameters

  [in] | slice | the reference memory.

Returns
  newly allocated memory or `NULL` on error

Since
  1.19

## eina_rw_slice_strdup()

char * eina_rw_slice_strdup | ( | const Eina_Rw_Slice | rw_slice | ) |

inline static

A null-terminated string for this slice.

Parameters

  [in] | rw_slice | the reference memory.

Returns
  newly allocated memory or `NULL` on error

Since
  1.19