NAME 
src/string.c - Parrot Strings
DESCRIPTION
This file implements the non-ICU parts of the Parrot string subsystem.
Note that bufstart and buflen are used by the memory subsystem The string functions may only use buflen to determine,
if there is some space left beyond bufused.
This is the only valid usage of these two data members,
beside setting bufstart/buflen for external strings.
String COW support
static void Parrot_unmake_COW(Interp *interpreter, STRING *s)- If the specified Parrot string is copy-on-write then the memory is copied over and the copy-on-write flag is cleared.
static void copy_string_header(Interp *interpreter, String *dest, String *src)- Copies the string header from the first Parrot string to the second.
static STRING *Parrot_make_COW_reference(Interp *interpreter, STRING *s)- Creates a copy-on-write string by cloning a string header without allocating a new buffer.
static STRING *Parrot_reuse_COW_reference(Interp *interpreter, STRING *s, STRING *reuse)- Creates a copy-on-write string by cloning a string header without allocating a new buffer. Doesn't allocate a new string header, instead using the one passed in
static void Parrot_make_COW_reference_from_header(Interp *interpreter, STRING *s, STRING *d)- Makes the second Parrot string a copy-on-write reference to first.
STRING *string_set(Interp *interpreter, STRING *dest, STRING *src)- Makes the contents of first Parrot string a copy of the contents of second.
Basic String Functions
Creation, enlargement, etc.
void string_init(Interp*)- Initializes the Parrot string subsystem.
void string_deinit(Interp*)- De-Initializes the Parrot string subsystem.
UINTVAL string_capacity(Interp *interpreter, STRING *s)- Returns the capacity of the specified Parrot string.
STRING *string_make_empty(Interp *interpreter, parrot_string_representation_t representation, UINTVAL capacity)- Creates and returns an empty Parrot string.
STRING *string_append(Interp *interpreter, STRING *a, STRING *b, UINTVAL Uflags)- Take in two Parrot strings and append the second to the first.
STRING *string_from_cstring(Interp *interpreter, const void *buffer, UINTVAL len)- Make a Parrot string from a specified C string.
STRING *string_from_const_cstring(Interp *interpreter, const void *buffer, UINTVAL len)- Make a Parrot string from a specified C string.
const char *string_primary_encoding_for_representation(Interp *interpreter, parrot_string_representation_t representation)- Returns the primary encoding for the specified representation.
- This is needed for packfile unpacking, unless we just always use UTF-8 or BOCU.
STRING *const_string(Interp *interpreter, const char *buffer)- Creates and returns a constant Parrot string.
STRING *string_make(Interp *interpreter, const void *buffer, UINTVAL len, const char *charset, UINTVAL flags)- Creates and returns a new Parrot string using
lenbytes of string data read frombuffer. - The value of
charsetspecifies the string's representation. The currently recognised values are: - If
charsetis unspecified the default charset 'iso-8859-1' will be used. - The value of
flagsis optionally one or morePObj_*flagsOR-ed together. STRING *string_grow(Interp *interpreter, STRING *s, INTVAL addlen)- Grows the Parrot string's buffer by the specified number of characters.
'iso-8859-1'
'ascii'
'binary'
Ordinary user-visible string operations
UINTVAL string_length(Interp *interpreter, const STRING *s)- Returns the number of characters in the specified Parrot string.
INTVAL string_index(Interp *interpreter, const STRING *s, UINTVAL idx)- Returns the character (or glyph, depending upon the string's encoding) This is to abstract the process of finding the Nth character in a (possibly unicode or JIS-encoded) string, the idea being that once the encoding functions are fleshed out, this function can do the right thing.
- Note that this is not range-checked.
INTVAL string_str_index(Interp *interpreter, const STRING *s, const STRING *s2, UINTVAL start)- Returns the character position of the second Parrot string in the first at or after
start. The return value is a (0 based) offset in characters, not bytes. If second string is not specified, then return -1. INTVAL string_ord(Interp *interpreter, const STRING *s, INTVAL idx)- Returns the codepoint at a given index into a string. Negative indexes are treated as counting from the end of the string.
STRING *string_chr(Interp *interpreter, UINTVAL character)- Returns a single character Parrot string.
- TODO - Allow this to take an array of characters?
STRING *string_copy(Interp *interpreter, STRING *s)- Creates and returns a copy of the specified Parrot string.
Vtable Dispatch Functions
INTVAL string_compute_strlen(Interp *interpreter, STRING *s)- Calculates and returns the number of characters in the specified Parrot string.
INTVAL string_max_bytes(Interp *interpreter, STRING *s, INTVAL nchars)- Returns the number of bytes required to safely contain the specified number of characters in the specified Parrot string's representation.
STRING *string_concat(Interp *interpreter, STRING *a, STRING *b, UINTVAL Uflags)- Concatenates two Parrot string. If necessary, converts the second string's encoding and/or type to match those of the first string. If either string is
NULL, then a copy of the non-NULLstring is returned. If both strings areNULL, then a new zero-length string is created and returned. STRING *string_repeat(Interp *interpreter, const STRING *s, UINTVAL num, STRING **d)- Repeats the specified Parrot string num times and stores the result in the second string, and returns it. The second string is created if necessary.
STRING *string_substr(Interp *interpreter, STRING *src, INTVAL offset, INTVAL length, STRING **d, int replace_dest)- Copies the substring of length
lengthfromoffsetfrom the specified Parrot string and stores it in**d, allocating memory if necessary. The substring is also returned. STRING *string_replace(Interp *interpreter, STRING *src, INTVAL offset, INTVAL length, STRING *rep, STRING **d)- This should follow the Perl semantics for:
- Replaces a sequence of
lengthcharacters fromoffsetin the first Parrot string with the second Parrot string, returning what was replaced. - Replacing a sequence of characters with a longer string grows the string; a shorter string shrinks it.
- Replacing 2 past the end of the string is undefined. However replacing 1 past the end of the string concatenates the two strings.
- A negative offset is allowed to replace from the end.
STRING *string_chopn(Interp *interpreter, STRING *s, INTVAL n)- Chops off the last
ncharacters of the specified Parrot string. Ifnis negative, cuts the string after+ncharacters. INTVAL string_equal(Interp *interpreter, STRING *s1, STRING *s2)- Compares two Parrot strings, performing type and encoding conversions if necessary.
- Note that this function returns 0 if the strings are equal and 1 otherwise.
static void make_writable(Interp *interpreter, STRING **s, const size_t len, parrot_string_representation_t representation)- Makes the specified Parrot string writable with minimum length
len. Therepresentationargument is required in case a new Parrot string has to be created. STRING *string_bitwise_and(Interp *interpreter, STRING *s1, STRING *s2, STRING **dest)- Performs a bitwise
ANDon two Parrot string, performing type and encoding conversions if necessary. If the second string is notNULLthen it is reused, otherwise a new Parrot string is created. STRING *string_bitwise_or(Interp *interpreter, STRING *s1, STRING *s2, STRING **dest)- Performs a bitwise
ORon two Parrot string, performing type and encoding conversions if necessary. If the second string is notNULLthen it is reused, otherwise a new Parrot string is created. STRING *string_bitwise_xor(Interp *interpreter, STRING *s1, STRING *s2, STRING **dest)- Performs a bitwise
XORon two Parrot strings, performing type and encoding conversions if necessary. If the second string is notNULLthen it is reused, otherwise a new Parrot string is created. STRING *string_bitwise_not(Interp *interpreter, STRING *s, STRING **dest)- Performs a bitwise
NOTon a Parrot string. If the second string is notNULLthen it is reused, otherwise a new Parrot string is created. INTVAL string_bool(Interp *interpreter, const STRING *s)- Returns whether the specified Parrot string is true. A string is true if it is equal to anything other than
0,""or"0". STRING *string_nprintf(Interp *interpreter, STRING *dest, INTVAL bytelen, const char *format, ...)- This is like
Parrot_snprintf()except that it writes to and returns a Parrot string. - Note that
bytelendoes not include space for a (non-existent) trailing'\0'.destmay be aNULLpointer, in which case a new native string will be created. Ifbytelenis 0, the behaviour becomes moresprintf-ish thansnprintf-like.bytelenis measured in the encoding of*dest. STRING *string_printf(Interp *interpreter, const char *format, ...)- Writes and returns a Parrot string.
INTVAL string_to_int(Interp *interpreter, const STRING *s)- Converts a numeric Parrot string to an integer value.
- A number is such that:
- The integer value is the appropriate integer representation of such a number, rounding towards zero.
FLOATVAL string_to_num(Interp *interpreter, const STRING *s)- Same as
string_to_int()except that a floating-point value is returned. STRING *string_from_int(Interp *interpreter, INTVAL i)- Returns a Parrot string representation of the specified integer value.
STRING *string_from_num(Interp *interpreter, FLOATVAL f)- Returns a Parrot string representation of the specified floating-point value.
char *string_to_cstring(Interp *interpreter, STRING *s)- Returns a C string for the specified Parrot string. Use
string_cstring_free()to free the string. Failure to do this will result in a memory leak. void string_cstring_free(void *ptr)- Free a string created by
string_to_cstring(). - TODO - Hopefully this can be a go away at some point, as it's got all sorts of leak potential otherwise.
void string_pin(Interp *interpreter, STRING *s)- Replace the apecified Parrot string's managed buffer memory by system memory.
void string_unpin(Interp *interpreter, STRING *s)- Undo a
string_pin()so that the string once again uses managed memory. size_t string_hash(Interp *interpreter, Hash *hash, STRING *s)- Returns the hash value for the specified Parrot string, caching it in
s-hashval>. STRING *string_unescape_cstring(Interp *interpreter, char *cstring, char delimiter, char *charset)- Unescapes the specified C string. These sequences are covered:
STRING *string_upcase(Interp *interpreter, const STRING *s)- Returns a copy of the specified Parrot string converted to upper case. Non-caseable characters are left unchanged.
- TODO - implemented only for ASCII.
void string_upcase_inplace(Interp *interpreter, STRING *s)- Converts the specified Parrot string to upper case.
STRING *string_downcase(Interp *interpreter, const STRING *s)- Returns a copy of the specified Parrot string converted to lower case. Non-caseable characters are left unchanged.
void string_downcase_inplace(Interp *interpreter, STRING *s)- Converts the specified Parrot string to lower case.
STRING *string_titlecase(Interp *interpreter, const STRING *s)- Returns a copy of the specified Parrot string converted to title case. Non-caseable characters are left unchanged.
void string_titlecase_inplace(Interp *interpreter, STRING *s)- Converts the specified Parrot string to title case.
STRING *string_increment(Interp *, const STRING *)- Perl5ish increment the string. Currently single char only.
substr EXPR, OFFSET, LENGTH, REPLACEMENT
sign = '+' | '-'
digit = "Any code point considered a digit by the chartype"
indicator = 'e' | 'E'
digits = digit [digit]...
decimal-part = digits '.' [digits] | ['.'] digits
exponent-part = indicator [sign] digits
numeric-string = [sign] decimal-part [exponent-part]
\xhh 1..2 hex digits
\ooo 1..3 oct digits
\cX control char X
\x{h..h} 1..8 hex digits
\uhhhh 4 hex digits
\Uhhhhhhhh 8 hex digits
\a, \b, \t, \n, \v, \f, \r, \e, \?
