Main Page | Data Structures | File List | Globals

libgu/gu_pcs.c File Reference

Perl Compatible Strings. More...

#include "before_system.h"
#include <stdio.h>
#include <string.h>
#include "gu.h"

Data Structures

struct  PCS

Functions

void * gu_pcs_new (void)
 create a PCS object

void * gu_pcs_new_pcs (void **pcs)
 create new PCS and initialize from a PCS

void * gu_pcs_new_cstr (const char cstr[])
 create new PCS and initialize from a char[]

void gu_pcs_free (void **pcs)
 destroy a PCS object

char * gu_pcs_free_keep_cstr (void **pcs)
 Destroy a PCS object but keep the C string.

void gu_pcs_debug (void **pcs, const char name[])
 print a description of a PCS object on stdout

void * gu_pcs_snapshot (void **pcs)
 obtain a copy of a PCS object that won't be unexpectedly changed

void gu_pcs_grow (void **pcs, int new_size)
 expand the internal storage of a PCS in anticipation of future growth

void gu_pcs_set_cstr (void **pcs, const char cstr[])
 copy a char[] into an existing PCS

void gu_pcs_set_pcs (void **pcs, void **pcs2)
 copy a PCS into an existing PCS

const char * gu_pcs_get_cstr (void **pcs)
 get pointer to const char[] within PCS

char * gu_pcs_get_editable_cstr (void **pcs)
 Get pointer to an editable char[] within PCS.

int gu_pcs_length (void **pcs)
 get length of PCS in bytes

int gu_pcs_truncate (void **pcs, size_t newlen)
 Truncate a PCS to a specified length in bytes.

void gu_pcs_append_char (void **pcs, int c)
 append char to PCS

void gu_pcs_append_cstr (void **pcs, const char cstr[])
 append C char[] to PCS

void gu_pcs_append_pcs (void **pcs, void **pcs2)
 append PCS to existing PCS

int gu_pcs_hash (void **pcs_key)
 create a hash value from a PCS

int gu_pcs_cmp (void **pcs1, void **pcs2)
 compare PCSs


Detailed Description

Perl Compatible Strings.

This module implements a string library. This library is designed to make it easier to port Perl code to C. The strings are stored in objects known as PCS (Perl Compatible String).

PCS objects can contain strings with embedded NULLs, but such string cannot be converted to C strings because C strings can't contain embedded NULLs.


Function Documentation

void gu_pcs_append_char void **  pcs,
int  c
 

append char to PCS

This function appends a C char to the the PCS object.

void gu_pcs_append_cstr void **  pcs,
const char  cstr[]
 

append C char[] to PCS

This function appends a C string the the PCS object.

=cut

void gu_pcs_append_pcs void **  pcs,
void **  pcs2
 

append PCS to existing PCS

This function appends a PCS object to the the PCS object.

int gu_pcs_cmp void **  pcs1,
void **  pcs2
 

compare PCSs

This function does for PCSs what strcmp() does for C strings.

void gu_pcs_free void **  pcs  ) 
 

destroy a PCS object

This function decrements the reference count of a PCS object and sets the pointer pointed to by pcs to NULL. If the reference counter reaches zero, then the object is freed.

const char* gu_pcs_get_cstr void **  pcs  ) 
 

get pointer to const char[] within PCS

This function returns a pointer to a NULL terminated C string which contains the value of the PCS object. This pointer may cease to be valid if the PCS object is modified or freed, so if you won't be using the value imediately, you should call gu_strdup() on the result. Also, the string should not be modified by using this pointer.

char* gu_pcs_get_editable_cstr void **  pcs  ) 
 

Get pointer to an editable char[] within PCS.

This function should be called if you intend to edit the string in place. If anyone else has a reference to it, a new copy will be made just for you. If you will change the length of the string, call gu_pcs_length() to determine the initial length. If you are enlarging the string, you need to call gu_pcs_grow() first. If you are making the string smaller, you should call gu_pcs_truncate() when you are done.

void gu_pcs_grow void **  pcs,
int  new_size
 

expand the internal storage of a PCS in anticipation of future growth

This function enlarges the specified PCS so that it can hold a string of the specified size (excluding final NULL). If the requested size is smaller than the current storage size, this has no effect.

int gu_pcs_hash void **  pcs_key  ) 
 

create a hash value from a PCS

This function hashes a PCS. The hash function is attibuted to P. J Weinberger.

int gu_pcs_length void **  pcs  ) 
 

get length of PCS in bytes

This function returns the length in bytes of the PCS in bytes.

void* gu_pcs_new void   ) 
 

create a PCS object

This function creates a new PCS (Perl compatible string) object and returns a void pointer which should be passed to other gu_pcs_*() functions in order to use it.

void* gu_pcs_new_cstr const char  cstr[]  ) 
 

create new PCS and initialize from a char[]

This function creates a new PCS and initializes it from the C character array (string) provided.

void* gu_pcs_new_pcs void **  pcs  ) 
 

create new PCS and initialize from a PCS

This function creates a new PCS and copies the string value from the a pre-existing PCS supplied as an argument.

void gu_pcs_set_cstr void **  pcs,
const char  cstr[]
 

copy a char[] into an existing PCS

This function copies the contents of a C string (a NULL terminated character array into the PCS object. The function may have to allocate a new object and change the pointer pointed to by I<pcs> to point to the new object. A new object will be allocated if the value has a reference count greater than one (which means it should be copied on write).

void gu_pcs_set_pcs void **  pcs,
void **  pcs2
 

copy a PCS into an existing PCS

This function copies the contents of a PCS into the PCS object. The function may have to allocate a new object and change the pointer pointed to by I<pcs> to point to the new object. A new object will be allocated if the value has a reference count greater than one (which means it should be copied on write).

void* gu_pcs_snapshot void **  pcs  ) 
 

obtain a copy of a PCS object that won't be unexpectedly changed

This function increments the reference count of a PCS object. A function should call this if it is going to keep a pointer to a PCS object that was passed to it as an argument. If an attempt is made to modify a PCS object with a non-zero reference count, a copy is made and the caller gets a modified copy, but the copy held by other code is unmodified.


Generated on Fri Feb 20 15:17:52 2004 for PPR Libraries by doxygen 1.3.5