Ruby 3.5.0dev (2025-09-18 revision 176b3b514d8f4bcea38a10f0567b760701e46058)
Data Structures | Macros | Enumerations | Functions
pm_string.h File Reference

(176b3b514d8f4bcea38a10f0567b760701e46058)

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

#include "prism/defines.h"
#include <assert.h>
#include <errno.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <sys/stat.h>
Include dependency graph for pm_string.h:
This graph shows which files directly or indirectly include this file:

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.
 

Enumerations

enum  pm_string_init_result_t { PM_STRING_INIT_SUCCESS = 0 , PM_STRING_INIT_ERROR_GENERIC = 1 , PM_STRING_INIT_ERROR_DIRECTORY = 2 }
 Represents the result of calling pm_string_mapped_init or pm_string_file_init. More...
 

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.
 
void pm_string_ensure_owned (pm_string_t *string)
 Ensure the string is owned.
 
int pm_string_compare (const pm_string_t *left, const pm_string_t *right)
 Compare the underlying lengths and bytes of two strings.
 

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 70 of file pm_string.h.

Enumeration Type Documentation

◆ pm_string_init_result_t

Represents the result of calling pm_string_mapped_init or pm_string_file_init.

We need this additional information because there is not a platform-agnostic way to indicate that the file that was attempted to be opened was a directory.

Enumerator
PM_STRING_INIT_SUCCESS 

Indicates that the string was successfully initialized.

PM_STRING_INIT_ERROR_GENERIC 

Indicates a generic error from a string_*_init function, where the type of error should be read from errno or GetLastError().

PM_STRING_INIT_ERROR_DIRECTORY 

Indicates that the file that was attempted to be opened was a directory.

Definition at line 105 of file pm_string.h.

Function Documentation

◆ pm_string_compare()

int pm_string_compare ( const pm_string_t left,
const pm_string_t right 
)

Compare the underlying lengths and bytes of two strings.

Returns 0 if the strings are equal, a negative number if the left string is less than the right string, and a positive number if the left string is greater than the right string.

Parameters
leftThe left string to compare.
rightThe right string to compare.
Returns
The comparison result.

Returns 0 if the strings are equal, a negative number if the left string is less than the right string, and a positive number if the left string is greater than the right string.

Definition at line 336 of file pm_string.c.

◆ 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
stringThe string to initialize.
sourceThe source of the string.
lengthThe 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
stringThe string to ensure is owned.

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

Definition at line 316 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
stringThe string to initialize.
sourceThe source of the string.
lengthThe 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
stringThe string to initialize.
startThe start of the string.
endThe 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.