pcre_get.c

Function pcre_get_stringnumber

This function is used by the two extraction functions below, as well as being generally available.

Synopsis

Prototype

int pcre_get_stringnumber (
      const pcre* code,
      const char* stringname
);

Type	Name	Read/Write	Description
const pcre*	code	Input	the compiled regex
const char*	stringname	Input	the name whose number is required
int		RETURN	the number of the named parentheses, or a negative number (PCRE_ERROR_NOSUBSTRING) if not found

Input

Returns

Description

This function is used by the two extraction functions below, as well as being generally available.

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_copy_substring

This function copies a single captured substring into a given buffer. Note that we use memcpy() rather than strncpy() in case there are binary zeros in the string.

Synopsis

Prototype

int pcre_copy_substring (
      const char* subject,
      const int* ovector,
      int stringcount,
      int stringnumber,
      char* buffer,
      int size
);

Type	Name	Read/Write	Description
const char*	subject	Input	the subject string that was matched
const int*	ovector	Input	pointer to the offsets table
int	stringcount	Input	the number of substrings that were captured (i.e. the yield of the pcre_exec call, unless that was zero, in which case it should be 1/3 of the offset table size)
int	stringnumber	Input	the number of the required substring
char*	buffer	Output	where to put the substring
int	size	Input	the size of the buffer
int		RETURN	if successful: the length of the copied string, not including the zero that is put on the end; can be zero if not successful: PCRE_ERROR_NOMEMORY (-6) buffer too small PCRE_ERROR_NOSUBSTRING (-7) no such captured substring

Input

Output

Returns

Description

This function copies a single captured substring into a given buffer. Note that we use memcpy() rather than strncpy() in case there are binary zeros in the string.

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_copy_named_substring

This function copies a single captured substring into a given buffer, identifying it by name.

Synopsis

Prototype

int pcre_copy_named_substring (
      const pcre* code,
      const char* subject,
      const int* ovector,
      int stringcount,
      const char* stringname,
      char* buffer,
      int size
);

Type	Name	Read/Write	Description
const pcre*	code	Input	the compiled regex
const char*	subject	Input	the subject string that was matched
const int*	ovector	Input	pointer to the offsets table
int	stringcount	Input	the number of substrings that were captured (i.e. the yield of the pcre_exec call, unless that was zero, in which case it should be 1/3 of the offset table size)
const char*	stringname	Input	the name of the required substring
char*	buffer	Output	where to put the substring
int	size	Input	the size of the buffer
int		RETURN	if successful: the length of the copied string, not including the zero that is put on the end; can be zero if not successful: PCRE_ERROR_NOMEMORY (-6) buffer too small PCRE_ERROR_NOSUBSTRING (-7) no such captured substring

Input

Output

Returns

Description

This function copies a single captured substring into a given buffer, identifying it by name.

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_get_substring_list

This function gets one chunk of store and builds a list of pointers and all of the captured substrings in it. A NULL pointer is put on the end of the list.

Synopsis

Prototype

int pcre_get_substring_list (
      const char* subject,
      const int* ovector,
      int stringcount,
      const char*** listptr
);

Type	Name	Read/Write	Description
const char*	subject	Input	the subject string that was matched
const int*	ovector	Output	pointer to the offsets table
int	stringcount	Input	the number of substrings that were captured (i.e. the yield of the pcre_exec call, unless that was zero, in which case it should be 1/3 of the offset table size)
const char***	listptr	Input	set to point to the list of pointers
int		RETURN	if successful: 0 if not successful: PCRE_ERROR_NOMEMORY (-6) failed to get store

Input

Output

Returns

Description

This function gets one chunk of store and builds a list of pointers and all of the captured substrings in it. A NULL pointer is put on the end of the list.

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_free_substring_list

This function exists for the benefit of people calling PCRE from non-C programs that can call its functions, but not free() or (pcre_free)() directly.

Synopsis

Prototype

void pcre_free_substring_list (
      const char** pointer
);

Type	Name	Read/Write	Description
const char**	pointer	Input	the result of a previous pcre_get_substring_list()
void		RETURN

Input

Returns

Description

This function exists for the benefit of people calling PCRE from non-C programs that can call its functions, but not free() or (pcre_free)() directly.

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_get_substring

This function copies a single captured substring into a piece of new store

Synopsis

Prototype

int pcre_get_substring (
      const char* subject,
      const int* ovector,
      int stringcount,
      int stringnumber,
      const char** stringptr
);

Type	Name	Read/Write	Description
const char*	subject	Input	the subject string that was matched
const int*	ovector	Input	pointer to the offsets table
int	stringcount	Input	the number of substrings that were captured (i.e. the yield of the pcre_exec call, unless that was zero, in which case it should be 1/3 of the offset table size)
int	stringnumber	Input	the number of the required substring
const char**	stringptr	Output	where to put a pointer to the substring
int		RETURN	if successful: the length of the string, not including the zero that is put on the end; can be zero if not successful: PCRE_ERROR_NOMEMORY (-6) failed to get store PCRE_ERROR_NOSUBSTRING (-7) substring not present

Input

Output

Returns

Description

This function copies a single captured substring into a piece of new store

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_get_named_substring

This function copies a single captured substring, identified by name, into new store.

Synopsis

Prototype

int pcre_get_named_substring (
      const pcre* code,
      const char* subject,
      const int* ovector,
      int stringcount,
      const char* stringname,
      const char** stringptr
);

Type	Name	Read/Write	Description
const pcre*	code	Input	the compiled regex
const char*	subject	Input	the subject string that was matched
const int*	ovector	Input	pointer to the offsets table
int	stringcount	Input	the number of substrings that were captured (i.e. the yield of the pcre_exec call, unless that was zero, in which case it should be 1/3 of the offset table size)
const char*	stringname	Input	the name of the required substring
const char**	stringptr	Output	where to put the pointer
int		RETURN	if successful: the length of the copied string, not including the zero that is put on the end; can be zero if not successful: PCRE_ERROR_NOMEMORY (-6) couldn't get memory PCRE_ERROR_NOSUBSTRING (-7) no such captured substring

Input

Output

Returns

Description

This function copies a single captured substring, identified by name, into new store.

Usage

Example

Errors

Dependencies

See Also

Availability

Function pcre_free_substring

This function exists for the benefit of people calling PCRE from non-C programs that can call its functions, but not free() or (pcre_free)() directly.

Synopsis

Prototype

void pcre_free_substring (
      const char** pointer
);

Type	Name	Read/Write	Description
const char**	pointer	Delete	the result of a previous pcre_get_substring()
void		RETURN

Output

Returns

Description

This function exists for the benefit of people calling PCRE from non-C programs that can call its functions, but not free() or (pcre_free)() directly.

Usage

Example

Errors

Dependencies

See Also

Availability