Chapter 4.7:  String & Date Manipulation

[TOP] [UP] [PREV] [NEXT]

This page contains subsections on translations,  line manipulation,  word manipulation,  character manipulation,  and dates.

4.7.1 Translations

$upper(words)

Converts all the text in words to upper case.

$upper1(words)

Converts the first letter of each word in words to upper case.

$lower(words)

Converts all the text in words to lower case.

$quote(words)

Treats all of the words as a single word.  It evaluates to the string words, with all of the blanks, tabs, and newlines replaced with non-printable control characters.  This function is useful in several different circumstances:

1. When comparing two multi-word strings, as in:
   $equal ($quote (string1) $quote (string2))

2. To combine several words as one argument to the include directive, as in:
   include file.i $(cnum) $quote(conference description)

3. To supply a multi-word string to a function that specifically expects a $quote'd string, such as $add_resp().

4. For complicated $if() functions, such as

   $unquote ($if (condition $quote(then some multi-word text) \
                                  else some multi-word text))

$unquote(words)

Undoes the effect of $quote() when explicitly necessary.  I.e. $unquote ($quote (words)) evaluates to the original, unmodified words.

4.7.2 Line manipulation

The first line in a string is line number 1.

$lines (n count str)

Evaluates to the first count lines of string str, starting with line number n.  Lines are separated by newline characters.  If count is -1, it uses all the remaining lines in str.

4.7.3 Word manipulation

The first word in a string is word number 1.

$set (a b)

Sets the variable named a to the string b.  Evaluates to nothing.  Equivalent to the Set directive, but usable as a function.

$words (n count str)

Evaluates to the first count words of string str, starting with word number n.  Words are separated by one or more spaces (or tabs, newlines, or Kanji double-wide spaces).  The first word is word number 1.  If count is -1, it uses all the remaining words in str.

$word(n str)

Evaluates to word number n of string str.  Equivalent to $words (n 1 str).  If n < 0, evaluates to the n'th word from the end.  Thus "$word (-1 str)" is the last word in str.

$rest(n str)

Evaluates to the "rest" of the words in a string, i.e. word number n through the end of str, inclusive.  Equivalent to $words (n -1 str).

$tablefind(word str)

Look for word in str.  If it is identical to a single word, evaluate to the number of that word in str.  Otherwise '0'.  (Note that $tablefind() effectively reduces all strings to lowercase before checking "identical to".  This may have originally been a bug.)

$tablematch(word str)

Look for word in str.  If it is identical to a single word, evaluate to the number of that word in str.  Otherwise '0'.  (This function does not convert to lowercase first.)

$sizeof(str)

Evaluates to the number of words in string str.

$numeric(str)

Evaluates to 1 if the (first word of) str is a number, and 0 otherwise.

$is_num(str)

Evaluates to the position of the first character in str which is not a number.  (A leading minus sign is considered to be part of a number.)

4.7.4 Character & Position Manipulation

The first character in a string is character number 0.

$pad(num)

Evaluates to num blanks.  Generally only useful inside <PRE> text.

$newline()

Evaluates to a newline character.  Useful inside arguments to functions such as $t2hbr(), $ad_item(), etc.

$replace(a b c)

Each of the strings a and b must either be single characters, or else the (two or more digit) base-ten numeric representation of a single character.  $replace() evaluates to string c, but with each instance of character a replaced by character b.

$asc2dec(text)

Converts text to a space-separated string of decimal numbers, representing the value of each character in text.

$wordpos(n str)

Evaluates to the character position in str of word number n.

$str_index(what text)

Find the first occurrence of the (one-word) string what in string text.  Evaluates to position number of what in text.  (The first position is 0.) Evaluates to "-1" if not found.

$str_replace(orig replace text)

Evaluates to text, with all all instances of orig replaced with replace.  $str_replace() automatically "unquotes" its first two arguments, so that multiple word orig or replace strings may supplied by $quote()ing them.

$str_revdex(what text))

Find the last occurrence of the (one-word) string what in text.  Evaluates to position number of what in text.  (The first position is 0.)  Evaluates to "-1" if not found.

$str_sub(pos len text)

Evaluates to a substring of text, starting at position pos, len characters long.

$strlen(text)

Evaluates to the number of characters in text.

$width(str)

Evaluates to the width (equivalent number of single-width characters) of str.  Double-wide kanji have a width of 2.

$charval(pos string)

Returns the decimal value of the pos'th character in string.  The first character in string is at position 0.  Positions beyond the end of the string return a character value of 0.

$charvals(string)    (v4.41)

Evaluates to the decimal values of every character in string, separated by (leading) spaces.

$char(cval)

Evaluates to the ASCII character with decimal value cval.  For example, $char(97) is the letter a.

4.7.5 Dates

$epoch(date)

Date must be a date of form DD-MMM-YY[YY].  The function evaluates to its equivalent "epoch" time, i.e. the number of seconds since Jan 1, 1970.  (See $time().)

$dateof(time)

Evaluates to the date form (DD-MMM-YYYY HH:MM) of an "epoch" time in seconds.

$weekday(time)

Evaluates to the number of the day of the week (Sunday=0, Monday=1, ... Saturday=6) of an "epoch" time in seconds.