/*
 * $Id: atnum.txt 15102 2010-07-14 12:48:39Z vszakats $
 */

/*  $DOC$
 *  $FUNCNAME$
 *      AFTERATNUM()
 *  $CATEGORY$
 *      CT3 string functions
 *  $ONELINER$
 *      Returns string portion after nth occurence of substring
 *  $SYNTAX$
 *      AFTERATNUM (<cStringToMatch>, <cString>, [<nCounter>],
 *                  [<nIgnore>] ) --> cRestString
 *  $ARGUMENTS$
 *      <cStringToMatch>    is the substring scanned for
 *      <cString>           is the scanned string
 *      [<nCounter>]        determines how many occurences are of
 *                          <cStringToMatch> in <cString> are searched
 *                          Default: search last occurence
 *      [<nIgnore>]         determines how many character from the start
 *                          should be ignored in the search
 *                          Default: 0
 *  $RETURNS$
 *      <cRestString>       the portion of <cString> after the <nCounter>th
 *                          occurence of <cStringToMatch> in <cString>
 *                          If such a rest does not exist, an empty string
 *                          is returned.
 *  $DESCRIPTION$
 *      This function scans <cString> for <cStringToMatch>. After the
 *      <nCounter>th match (or the last one, depending on the value of
 *      <nCounter>) has been found, the portion of
 *      <cString> after that match will be returned. If there aren't enough
 *      matches or the last match is identical to the end of <cString>, an
 *      empty string will be returned.
 *      After a match has been found, the function continues to scan after
 *      that match if the CSETATMUPA() switch is turned off, with the
 *      second character of the matched substring otherwise.
 *      The function will also consider the settings of SETATLIKE().
 *  $EXAMPLES$
 *      ? AFTERATNUM ("!", "What is the answer ? 4 ! 5 !") -> ""
 *      ? AFTERATNUM ("!", "What is the answer ? 4 ! 5 ?") -> " 5 ?"
 *      <TODO: add some examples here with csetatmupa() and setatlike()>
 *  $TESTS$
 *      AFTERATNUM ("..", "..This..is..a..test!") == "test!"
 *      AFTERATNUM ("..", "..This..is..a..test!", 2) == "is..a..test!"
 *      AFTERATNUM ("..", "..This..is..a..test!", 2, 2) == "a..test!"
 *  $STATUS$
 *      Ready
 *  $COMPLIANCE$
 *      AFTERATNUM() is compatible with CT3's AFTERATNUM().
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Source is atnum.c, library is libct.
 *  $SEEALSO$
 *      ATNUM(),BEFORATNUM(),CSETATMUPA(),SETATLIKE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      BEFORATNUM()
 *  $CATEGORY$
 *      CT3 string functions
 *  $ONELINER$
 *      Returns string portion before nth occurence of substring
 *  $SYNTAX$
 *      BEFORATNUM (<cStringToMatch>, <cString>, [<nCounter>],
 *                  [<nIgnore>] ) --> cRestString
 *  $ARGUMENTS$
 *      <cStringToMatch>    is the substring scanned for
 *      <cString>           is the scanned string
 *      [<nCounter>]        determines how many occurences are of
 *                          <cStringToMatch> in <cString> are searched
 *                          Default: search last occurence
 *      [<nIgnore>]         determines how many character from the start
 *                          should be ignored in the search
 *                          Default: 0
 *  $RETURNS$
 *      <cRestString>       the portion of <cString> before the <nCounter>th
 *                          occurence of <cStringToMatch> in <cString>
 *                          If such a string does not exist, an empty string
 *                          is returned.
 *  $DESCRIPTION$
 *      This function scans <cString> for <cStringToMatch>. After the
 *      <nCounter>th match (or the last one, depending on the value of
 *      <nCounter>) has been found, the portion of
 *      <cString> before that match will be returned. If there aren't enough
 *      matches or the last match is identical to the start of <cString>
 *      (i.e. the last match is the first match), an empty string will be returned.
 *      After a match has been found, the function continues to scan after
 *      that match if the CSETATMUPA() switch is turned off, with the
 *      second character of the matched substring otherwise.
 *      The function will also consider the settings of SETATLIKE().
 *  $EXAMPLES$
 *      ? BEFORATNUM ("!", "What is the answer ? 4 ! 5 !") -> "What is the answer ? 4 ! 5 "
 *      ? BEFORATNUM ("!", "What is the answer ? 4 ! 5 ?") -> "What is the answer ? 4 "
 *      <TODO: add some examples here with csetatmupa() and setatlike()>
 *  $TESTS$
 *      BEFORATNUM ("..", "..This..is..a..test!") == "..This..is..a"
 *      BEFORATNUM ("..", "..This..is..a..test!", 2) == "..This"
 *      BEFORATNUM ("..", "..This..is..a..test!", 2, 2) == "..This..is"
 *  $STATUS$
 *      Ready
 *  $COMPLIANCE$
 *      BEFORATNUM() is compatible with CT3's BEFORATNUM().
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Source is atnum.c, library is ct3.
 *  $SEEALSO$
 *      ATNUM()  AFTERATNUM()  CSETATMUPA()  SETATLIKE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ATNUM()
 *  $CATEGORY$
 *      CT3 string functions
 *  $ONELINER$
 *      Returns the start position of the nth occurence of a substring in a string
 *  $SYNTAX$
 *      ATNUM (<cStringToMatch>, <cString>, [<nCounter>],
 *             [<nIgnore>] ) --> nPosition
 *  $ARGUMENTS$
 *      <cStringToMatch>    is the substring scanned for
 *      <cString>           is the scanned string
 *      [<nCounter>]        determines how many occurences are of
 *                          <cStringToMatch> in <cString> are searched
 *                          Default: search last occurence
 *      [<nIgnore>]         determines how many character from the start
 *                          should be ignored in the search
 *                          Default: 0
 *  $RETURNS$
 *      <nPosition>         the position of the <nCounter>th
 *                          occurence of <cStringToMatch> in <cString>.
 *                          If such an occurence does not exist, 0
 *                          is returned.
 *  $DESCRIPTION$
 *      This function scans <cString> for <cStringToMatch>. After the
 *      <nCounter>th match (or the last one, depending on the value of
 *      <nCounter>) has been found, the position of
 *      that match will be returned. If there aren't enough
 *      matches or there is no last match, 0 will be returned.
 *      After a match has been found, the function continues to scan after
 *      that match if the CSETATMUPA() switch is turned off, with the
 *      second character of the matched substring otherwise.
 *      The function will also consider the settings of SETATLIKE().
 *  $EXAMPLES$
 *      ? ATNUM ("!", "What is the answer ? 4 ! 5 !") -> 28
 *      ? ATNUM ("!", "What is the answer ? 4 ! 5 ?") -> 24
 *      <TODO: add some examples here with csetatmupa() and setatlike()>
 *  $TESTS$
 *      ATNUM ("..", "..This..is..a..test!") == 14
 *      ATNUM ("..", "..This..is..a..test!", 2) == 7
 *      ATNUM ("..", "..This..is..a..test!", 2, 2) == 11
 *  $STATUS$
 *      Ready
 *  $COMPLIANCE$
 *      ATNUM() is compatible with CT3's ATNUM().
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Source is atnum.c, library is libct.
 *  $SEEALSO$
 *      ATNUM()  AFTERATNUM()  CSETATMUPA()  SETATLIKE()
 *  $END$
 */
