Pike Manual

17.2.3 struct pike_string

A struct pike_string is the internal representation of a string. Since Pike relies heavily on string manipulation, there are quite a few features and quirks to using this data structure. The most important part is that strings are shared. This means that after a string has been entered into the shared string table it must never be modified. Since some other thread might be using the very same string, it is not even permitted to change a shared string temporarily and then change it back.

A struct pike_string has these members:

INT32 refs;: The references to this string.
INT32 length;: This is the length of the string.
unsigned INT32 hval;: This is the internal hash value for the string, you should not have to use this member for any reason.
struct pike_string *next;: This points to the next string in the hash table. Internal use only.
int size_shift;: This represents the size of the characters in the string. Currently size_shift has three valid values: 0, 1 and 2. These values mean that the characters in the string are 1, 2 and 4 bytes long respectively.
char str[1];: This is the actual data. Note that you should never use this member directly. Use STR0, STR1 and STR2 instead.

General string management

Since pike strings are shared, you can compare them by using ==. FIXME -- add more here.

FUNCTION: STR0 - Get a pointer to a 'char'
SYNTAX: p_wchar0 *STR0(struct pike_string *s); p_wchar1 *STR1(struct pike_string *s); p_wchar2 *STR2(struct pike_string *s);
DESCRIPTION: These macros return raw C pointers to the data in the string s. Note that you may only use STR0 on strings where size_shift is 0, STR1 on strings where size_shift is 1 and STR2on strings where size_shift is 2. When compiled with DEBUG these macros will call fatal if used on strings with the wrong size_shift.
NOTE: All pike strings have been zero-terminated for your convenience.
The zero-termination is not included in the length of the string.

FUNCTION: free_string - Free a reference to a pike_string
SYNTAX: void free_string(struct pike_string *s);
DESCRIPTION: This function frees one reference to a pike string and if that is the last reference, it will free the string itself. As with all refcounting functions you should be careful about how you use it. If you forget to call this when you should, a memory leak will occur. If you call this function when you shouldn't Pike will most likely crash.

FUNCTION: make_shared_string - Make a new shared string
SYNTAX: struct pike_string *make_shared_string(char *str);
DESCRIPTION: This function takes a null terminated C string as argument and returns a pike_string with the same contents. It does not free or change str. The returned string will have a reference which will be up to you to free with free_string unless you send the string to a function such as push_string which eats the reference for you.
SEE ALSO

FUNCTION: make_shared_binary_string - Make a new binary shared string
SYNTAX: struct pike_string *make_shared_binary_string(char *str, INT32 len);
DESCRIPTION: This function does essentially the same thing as make_shared_string, but you give it the length of the string str as a second argument. This allows for strings with zeros in them. It is also more efficient to call this routine if you already know the length of the string str.
SEE ALSO

FUNCTION

begin_shared_string - Start building a shared string

SYNTAX

struct pike_string *begin_shared_string(INT32 len);

DESCRIPTION

This function is used to allocate a new shared string with a specified length which has not been created yet. The returned string is not yet shared and should be initialized with data before calling end_shared_string on it.

If after calling this function you decide that you do not need this string after all, you can simply call free on the returned string to free it. It is also possible to call free_string(end_shared_string(s)) but that would be much less efficient.

EXAMPLE

// This is in effect equal to s=make_shared_string("test") struct pike_string *s=begin_shared_string(4); STR0(s)[0]='t'; STR0(s)[1]='e'; STR0(s)[2]='s'; STR0(s)[3]='t'; s=end_shared_string(s);

SEE ALSO

begin_wide_shared_string, free_string, push_string, make_shared_string and end_shared_string

FUNCTION: end_shared_string - Insert a pre-allocated string into the shared string table
SYNTAX: struct pike_string *end_shared_string(struct pike_string *s);
DESCRIPTION: This function is used to finish constructing a pike string previously allocated with begin_shared_string or begin_wide_shared_string. It will insert the string into the shared string table. If there already is such a string in the shared string table then s will be freed and that string will be returned instead. After calling this function, you may not modify the string any more. As with make_shared_string this function returns a string with a reference which it is your responsibility to free.
SEE ALSO

FUNCTION: begin_wide_shared_string - Start building a wide shared string
SYNTAX: struct pike_string *begin_wide_shared_string(INT32 len, int size_shift);
DESCRIPTION: This function is a more generic version of begin_shared_string. It allocates space for a string of length len where each character is 1 << size_shift bytes. As with begin_shared_string it is your responsibility to initialize the string and to call end_shared_string on it.
EXAMPLE: struct pike_string *s=begin_wide_shared_string(1,2); STR2(s)[0]=4711; s=end_shared_string(s);
SEE ALSO

FUNCTION: make_shared_string1 - Make a wide shared string
SYNTAX: struct pike_string *make_shared_string1(p_whcar1 *str); struct pike_string *make_shared_binary_string1(p_whcar1 *str,INT32 len); struct pike_string *make_shared_string2(p_whcar2 *str); struct pike_string *make_shared_binary_string2(p_whcar2 *str,INT32 len);
DESCRIPTION: These functions are the wide string equivialents of make_shared_string and make_shared_binary_string. The functions ending in 1 use 2-byte characters and the ones ending in 2 use 4-byte characters.
SEE ALSO

Previous section

To contents

Next section