Ruby: prism/util/pm_string.h File Reference

Ruby 3.3.6p108 (2024-11-05 revision 75015d4c1f6965b5e85e96fb309f1f2129f933c0)

Data Structures | Macros | Functions
pm_string.h File Reference

A generic string type that can have various ownership semantics. More...

`#include "prism/defines.h"`
`#include <assert.h>`
`#include <stdbool.h>`
`#include <stddef.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <fcntl.h>`
`#include <sys/mman.h>`
`#include <sys/stat.h>`
`#include <unistd.h>`

Go to the source code of this file.

## Data Structures
struct | pm_string_t
| A generic string type that can have various ownership semantics. More...

## Macros
#define | PM_STRING_EMPTY ((pm_string_t) { .type = PM_STRING_CONSTANT, .source = NULL, .length = 0 })
| Defines an empty string.

## Functions
PRISM_EXPORTED_FUNCTION size_t | pm_string_sizeof (void)
| Returns the size of the pm_string_t struct.
void | pm_string_shared_init (pm_string_t *string, const uint8_t *start, const uint8_t *end)
| Initialize a shared string that is based on initial input.
void | pm_string_owned_init (pm_string_t *string, uint8_t *source, size_t length)
| Initialize an owned string that is responsible for freeing allocated memory.
void | pm_string_constant_init (pm_string_t *string, const char *source, size_t length)
| Initialize a constant string that doesn't own its memory source.
PRISM_EXPORTED_FUNCTION bool | pm_string_mapped_init (pm_string_t *string, const char *filepath)
| Read the file indicated by the filepath parameter into source and load its contents and size into the given `pm_string_t`.
size_t | pm_string_memsize (const pm_string_t *string)
| Returns the memory size associated with the string.
void | pm_string_ensure_owned (pm_string_t *string)
| Ensure the string is owned.
PRISM_EXPORTED_FUNCTION size_t | pm_string_length (const pm_string_t *string)
| Returns the length associated with the string.
PRISM_EXPORTED_FUNCTION const uint8_t * | pm_string_source (const pm_string_t *string)
| Returns the start pointer associated with the string.
PRISM_EXPORTED_FUNCTION void | pm_string_free (pm_string_t *string)
| Free the associated memory of the given string.

## Detailed Description

A generic string type that can have various ownership semantics.

Definition in file pm_string.h.

## Macro Definition Documentation

## ◆ PM_STRING_EMPTY

#define PM_STRING_EMPTY ((pm_string_t) { .type = PM_STRING_CONSTANT, .source = NULL, .length = 0 })

Defines an empty string.

This is useful for initializing a string that will be filled in later.

Definition at line 65 of file pm_string.h.

Referenced by pm_parser_init().

## Function Documentation

## ◆ pm_string_constant_init()

void pm_string_constant_init | ( | pm_string_t * | string,
|  | const char * | source,
|  | size_t | length )

Initialize a constant string that doesn't own its memory source.

Parameters

  string | The string to initialize.
  source | The source of the string.
  length | The length of the string.

Definition at line 42 of file pm_string.c.

## ◆ pm_string_ensure_owned()

void pm_string_ensure_owned | ( | pm_string_t * | string | ) |

Ensure the string is owned.

If it is not, then reinitialize it as owned and copy over the previous source.

Parameters

  string | The string to ensure is owned.

If it is not, then reinitialize it as owned and copy over the previous source.

Definition at line 165 of file pm_string.c.

## ◆ pm_string_free()

PRISM_EXPORTED_FUNCTION void pm_string_free | ( | pm_string_t * | string | ) |

Free the associated memory of the given string.

Parameters

  string | The string to free.

Definition at line 198 of file pm_string.c.

## ◆ pm_string_length()

PRISM_EXPORTED_FUNCTION size_t pm_string_length | ( | const pm_string_t * | string | ) |

Returns the length associated with the string.

Parameters

  string | The string to get the length of.

Returns
  The length of the string.

Definition at line 182 of file pm_string.c.

## ◆ pm_string_mapped_init()

PRISM_EXPORTED_FUNCTION bool pm_string_mapped_init | ( | pm_string_t * | string,
|  | const char * | filepath )

Read the file indicated by the filepath parameter into source and load its contents and size into the given `pm_string_t`.

The given `pm_string_t` should be freed using `pm_string_free` when it is no longer used.

We want to use demand paging as much as possible in order to avoid having to read the entire file into memory (which could be detrimental to performance for large files). This means that if we're on windows we'll use `MapViewOfFile`, on POSIX systems that have access to `mmap` we'll use `mmap`, and on other POSIX systems we'll use `read`.

Parameters

  string | The string to initialize.
  filepath | The filepath to read.

Returns
  Whether or not the file was successfully mapped.

The given `pm_string_t` should be freed using `pm_string_free` when it is no longer used.

We want to use demand paging as much as possible in order to avoid having to read the entire file into memory (which could be detrimental to performance for large files). This means that if we're on windows we'll use `MapViewOfFile`, on POSIX systems that have access to `mmap` we'll use `mmap`, and on other POSIX systems we'll use `read`.

Definition at line 62 of file pm_string.c.

## ◆ pm_string_memsize()

size_t pm_string_memsize | ( | const pm_string_t * | string | ) |

Returns the memory size associated with the string.

Parameters

  string | The string to get the memory size of.

Returns
  The size of the memory associated with the string.

Definition at line 152 of file pm_string.c.

## ◆ pm_string_owned_init()

void pm_string_owned_init | ( | pm_string_t * | string,
|  | uint8_t * | source,
|  | size_t | length )

Initialize an owned string that is responsible for freeing allocated memory.

Parameters

  string | The string to initialize.
  source | The source of the string.
  length | The length of the string.

Definition at line 30 of file pm_string.c.

## ◆ pm_string_shared_init()

void pm_string_shared_init | ( | pm_string_t * | string,
|  | const uint8_t * | start,
|  | const uint8_t * | end )

Initialize a shared string that is based on initial input.

Parameters

  string | The string to initialize.
  start | The start of the string.
  end | The end of the string.

Definition at line 16 of file pm_string.c.

## ◆ pm_string_sizeof()

PRISM_EXPORTED_FUNCTION size_t pm_string_sizeof | ( | void |  | ) |

Returns the size of the pm_string_t struct.

This is necessary to allocate the correct amount of memory in the FFI backend.

Returns
  The size of the pm_string_t struct.

This is necessary to allocate the correct amount of memory in the FFI backend.

Definition at line 8 of file pm_string.c.

## ◆ pm_string_source()

PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source | ( | const pm_string_t * | string | ) |

Returns the start pointer associated with the string.

Parameters

  string | The string to get the start pointer of.

Returns
  The start pointer of the string.

Definition at line 190 of file pm_string.c.