RowContainingValue ( data ; firstColumnValue ; columnSeparator ; rowSeparator )

RowContainingValue.fmfn

/**
 * =====================================
 * RowContainingValue ( data ; firstColumnValue ; columnSeparator ; rowSeparator )
 *
 * RETURNS:
 *		First row from an array of data where the first columns value matches.
 *		WITHOUT trailing column separator.
 *
 * PARAMETERS:
 *		data: array of data with single characters delimiting columns/rows
 *		firstColumnValue: Entire value to be found in the first column.
 *		columnSeparator: Character used to separate fields in the data.
 *			will default to comma "," if empty
 *		rowSeparator: Character used to separate records in the data.
 *			will default to a carriage return "¶" if empty
 *
 * DEPENDENCIES: none
 *
 * EXAMPLE:
 *		RowContainingValue (
 *			List (
 *				"a|b|c" ;
 *				"1|2|3" ;
 *				"apple|banana|cantaloup"
 *			) ;
 *			"apple" ;	/* firstColumnValue */
 *			"|" ;	/* columnSeparator */
 *			""	/* rowSeparator, default = ¶ */
 *		) = "apple|banana|cantaloup"
 *
 * NOTE:
 *		This doesn't really need to be a recursive function but I created it by
 *		modifying ColumnSlice, which is recursive, so it already had that format.
 *		I may modify this function to return all found rows instead of just the first,
 *		but for now, all I need is the first found row. So, since this future use
 *		case would require a recursive function, I left the format as-is.
 *
 * HISTORY:
 *		CREATED on 2014-DEC-10 by Daniel Smith <http://scr.im/dansmith>
 * =====================================
 */

Case (
	/* Step 0, set-up */
	not $~rcs.step ;
		Let ( [
			$~rcs.result = "" ;
			$~rcs.step = 1 ;
			columnSeparator = If ( not IsEmpty ( columnSeparator ) ;
				columnSeparator ;
				","
			) ;
			rowSeparator = If ( not IsEmpty ( rowSeparator ) ;
				rowSeparator ;
				"¶"
			)
		] ;
			RowContainingValue ( data ; firstColumnValue ; columnSeparator ; rowSeparator )
		) ;

	/* Step 1, gather values from specified column */
	$~rcs.step = 1 ;
		Let ( [
			~startOfRow = Position (
				rowSeparator & data ;
				rowSeparator & firstColumnValue & columnSeparator ;
				1 ; 	/* start */
				1 	/* occurrence */
			) ;
			~endOfRow = If ( ~startOfRow  ;
				Position (
					data & rowSeparator ;
					rowSeparator ;
					~startOfRow ; 	/* start */
					1 	/* occurrence */
				)
			) ;
			~row = If ( ~startOfRow  ;
				Middle ( data ; ~startOfRow ; ~endOfRow - ~startOfRow )
			) ;
			
			$~rcs.result = ~row ;
			$~rcs.step = 2
		] ;
			RowContainingValue ( "" ; "" ; "" ; "" )
		) ;

	/* Step 2, clean-up and return result */
	$~rcs.step = 2 ;
		Let ( [
			~result = $~rcs.result ;

			// purge variables
			$~rcs.result = "" ;
			$~rcs.step = ""
		] ;
			~result
		)
)