Modifying Strings

strcpy(char *tostr, char *fromstr)

strncpy(char *tostr, char *fromstr, int count)

copy_expanding(char *src, char **dest, int minlen)

The strcpy( ) primitive copies the null-terminated string fromstr to the array at tostr, including the terminating null character. The strncpy( ) primitive does the same, but always stops when count characters have been transferred, adding an additional null character to the string at tostr if necessary.

The copy_expanding( ) subroutine helps work with text that has no fixed length, stored in a dynamically allocated character pointer, not a fixed-length character array. Pass a pointer to a char * variable as dest, and the subroutine will resize it as needed to hold src. The char * variable may hold NULL initially. The minlen parameter provides a minimum allocation length for the result.

strcat(char *tostr, char *fromstr) strncat(char *tostr, char *fromstr, int count)
The strcat( ) primitive concatenates (or appends) the string at fromstr after the string at tostr. For example, if fromstr points at the constant string "def" and tostr is an array of 10 characters that contains "abc" (and then, of course, a null character, plus 6 more characters with any value), then strcat(tostr, fromstr); makes the array tostr contain "abcdef" followed by a null character and 3 unused characters.

The strncat( ) primitive works similarly. It appends at most count characters from fromstr, and ensures that the result is zero-terminated by adding a null character if necessary. Note that the count limits the number of characters appended, not the total number of characters in the string.

set_chars(char *ptr, char value, int count)
The set_chars( ) primitive sets all the count characters in a character array ptr to the given value.

int sprintf(char *dest, char *format, ...)
The sprintf( ) primitive is the most powerful string building primitive Epsilon provides. It takes two or more arguments. The first is a character array. The remaining arguments are in the format that say( ) uses: a format string possibly followed by more arguments. (See Printf-style Format Strings.) Instead of printing the string that is built on the screen, it copies the string into the destination array, and returns the number of characters copied.

int expand_string_template(char *dest, char *template, char *keys, char *vals[])
The expand_string_template( ) subroutine uses a template to construct a new string dest. The template contains zero or more escape sequences, each a percent character % followed by another letter. The subroutine replaces each escape sequence with its corresponding value. The allowed escape sequence characters should be listed in keys, and their replacement values should be listed in the array of strings vals in the same order. Epsilon will interpolate the sequences to construct dest, returning nonzero to indicate an error in the template (usually an unknown escape sequence).

For instance, if keys contains "ad", and the supplied vals array has been set so vals[0] is "happy" and vals[1] is "tiger", then the template "the %a is %d today" is copied to dest as "the tiger is happy today", and the subroutine will return 0.

The subroutine provides two built-in codes. For %x, it substitutes the directory name that contains Epsilon's executable. For %X, it substitutes the same, but (under Windows) converted to its 8.3 filename alias using the convert_to_8_3_filename( ) primitive. These built-in codes shouldn't appear in the keys string.

Previous Up Next
Examining Strings Primitives and EEL Subroutines Byte Arrays