letter_sequence/sequence/

builder.rs

use crate::sequence::helper::*;
use std::convert::From;
use std::convert::TryFrom;
use super::*;

/// ```rust
/// use letter_sequence::SequenceBuilder;
/// use std::convert::TryFrom;
///
/// let mut seq = SequenceBuilder::try_from("Z")
///   .unwrap()
/// 	.upper()
/// 	.build()
/// 	.unwrap();
/// // First call to .next() returns starting element
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "Z" );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "AA" );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "AB" );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "AC" );
/// ```
///
/// This time with .max_render_capacity() set, and lowercase
/// ```rust
/// use letter_sequence::SequenceBuilder;
/// use std::convert::TryFrom;
///
/// let mut seq = SequenceBuilder::try_from('y')
///   .unwrap()
/// 	.lower()
/// 	.max_render_capacity(1)
/// 	.build()
/// 	.unwrap();
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "y"  );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "z"  );
/// // Without .max_render_capacity(1) this would return "aa"
/// let elem = seq.next();
/// assert_eq!( elem, None  );
/// ```
///
/// Also boring number sequence
/// ```rust
/// use letter_sequence::SequenceBuilder;
/// use std::convert::TryFrom;
///
/// let mut seq = SequenceBuilder::from(102)
/// 	.numeric()
/// 	.build()
/// 	.unwrap();
/// let elem = seq.next();
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "103" );
/// ```
///
/// You can also set the step!
/// ```rust
/// use letter_sequence::SequenceBuilder;
/// use std::convert::TryFrom;
/// 
/// let mut seq = SequenceBuilder::from(0)
/// 	.numeric()
/// 	.step(2)
/// 	.build()
/// 	.unwrap();
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "0"  );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "2"  );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "4"  );
///
/// let mut seq = SequenceBuilder::try_from("A")
///   .unwrap()
/// 	.step(2)
/// 	.upper()
/// 	.build()
/// 	.unwrap();
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "A" );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "C" );
/// let elem = seq.next().unwrap();
/// assert_eq!( elem.to_string(), "E" );
/// ```
#[derive(Debug)]
pub struct SequenceBuilder {
	start: u64,
	step: u32,
	inclusive: bool,
	renderer: SeqRendererBuilder,
	min_render_length: Option<u8>,
	end: Option<u64>
}

impl Default for SequenceBuilder {
	fn default() -> Self {
		Self {
			start: 0,
			step: 1,
			end: None,
			inclusive: false,
			renderer: Default::default(),
			min_render_length: Default::default(),
		}
	}
}

impl SequenceBuilder {
	pub fn new() -> Self {
		Self { ..Default::default() }
	}


	/// Sets the end, default half-open (exclusive end), see .inclusive()
	pub fn end(mut self, end: u64) -> Self {
		self.end = Some(end);
		self
	}
	
	/// Sets the start
	pub fn start(mut self, start: u64) -> Self {
		self.start = start;
		self
	}
	
	/// Sets the increment to step to
	pub fn step(mut self, step: u32) -> Self {
		self.step = step;
		self
	}


	/// Limits the chacters in rendered output, incrementing past limit generates
	/// error. default: unlimited
	///
	/// ```rust
	/// use letter_sequence::{ SequenceBuilder, SequenceError };
	/// use std::convert::TryFrom;
	/// let mut seq = SequenceBuilder::try_from("y").unwrap().max_render_capacity(1).build().unwrap();
	/// let elem = seq.next().unwrap();
	/// assert_eq!( elem.to_string(), "y" );
	/// let elem = seq.next().unwrap();
	/// assert_eq!( elem.to_string(), "z" );
	/// assert_eq!( seq.next(), None );
	/// assert_eq!( seq.next(), None );
	/// ```
	pub fn max_render_capacity(mut self, chars: u8) -> Self {
		self.renderer = self.renderer.capacity(chars);
		self
	}

	/// Limits the minimum width of the rendered output, this only works on
	/// numeric which effectively zero-pads the output.
	pub fn min_render_length(mut self, chars: u8) -> Self {
		self.min_render_length = Some(chars);
		self
	}

	/// This is the default: a half-open range that excludes the end
	pub fn exclusive(mut self) -> Self {
		self.inclusive = false;
		self
	}
	
	/// Close the range, include the end
	pub fn inclusive(mut self) -> Self {
		self.inclusive = true;
		self
	}
	
	/// Render the sequence in lowercase
	pub fn lower(mut self) -> Self {
		self.renderer = SeqRendererBuilder::lower();
		self
	}
	/// Render the sequence in uppercase, default
	pub fn upper(mut self) -> Self {
		self.renderer = SeqRendererBuilder::upper();
		self
	}
	/// Render the sequence in digits
	pub fn numeric(mut self) -> Self {
		self.renderer = SeqRendererBuilder::numeric();
		self
	}

	pub fn build(self) -> Result<Sequence, SequenceError> {
		let renderer = self.renderer.build()?;

		// You can't really pad alpha-numerics because A is not 0.
		match (renderer.display(), self.min_render_length) {
			(RenderDisplay::Upper | RenderDisplay::Lower, Some(_)) => return Err(SequenceError::PaddingAlpha),
			_ => ()
		};

		let end = match (self.end, self.inclusive) {
			(Some(end), true) => Some(end + 1),
			(Some(end), false) => Some(end),
			_ => None
		};
		let seq = Sequence {
			end,
			step: self.step,
			start: self.start,
			renderer,
			.. Default::default()
		};
		Ok(seq)
	}
}

impl From<u64> for SequenceBuilder {
	fn from(start: u64) -> Self {
		Self::new().start(start)
	}
}

/// ```rust
/// // use letter_sequence::SequenceBuilder;
/// // use std::convert::TryFrom;
///	// assert_eq!(
///	// 	SequenceBuilder::try_from("00001")
///	// 		.unwrap()
///	// 		.build()
///	// 		.unwrap()
///	// 		.to_string(),
///	// 	"1"
///	// );
///	// assert_eq!(
///	// 	SequenceBuilder::try_from("00001")
///	// 		.unwrap()
///	// 		.upper()
///	// 		.build()
///	// 		.unwrap()
///	// 		.to_string(),
///	// 	"B"
///	// );
/// ```
impl TryFrom<&str> for SequenceBuilder {
	type Error = SequenceError;
	fn try_from(value: &str) -> Result<Self, Self::Error> {
		let first_char = value
			.chars()
			.next()
			.ok_or_else( || SequenceError::EmptyString )?
		;

		match renderer::RenderDisplay::try_from(first_char)? {
			renderer::RenderDisplay::Numeric => Ok(
				Self::new().start(value.parse::<u64>()?).numeric()
			),
			renderer::RenderDisplay::Upper => Ok(
				Self::new().start(string_to_int(&value)?).upper()
			),
			renderer::RenderDisplay::Lower => Ok(
				Self::new().start(string_to_int(&value)?).lower()
			)
		}
	}
}

impl TryFrom<(&str, &str)> for SequenceBuilder {
	type Error = SequenceError;
	fn try_from((start, end): (&str, &str)) -> Result<Self, Self::Error> {
		let first_char = start
			.chars()
			.next()
			.ok_or_else( || SequenceError::EmptyString )?
		;

		let builder = match renderer::RenderDisplay::try_from(first_char)? {
			renderer::RenderDisplay::Numeric => {
				Self::new()
					.start(start.parse::<u64>()?)
					.end(end.parse::<u64>()?)
					.numeric()
			},
			renderer::RenderDisplay::Upper => {
				Self::new()
					.start(string_to_int(&start)?)
					.end(string_to_int(&end)?)
					.upper()
			},
			renderer::RenderDisplay::Lower => {
				Self::new()
					.start(string_to_int(&start)?)
					.end(string_to_int(&end)?)
					.lower()
			}
		};

		Ok(builder)
	}
}

impl TryFrom<char> for SequenceBuilder {
	type Error = SequenceError;
	fn try_from(value: char) -> Result<Self, Self::Error> {
		Ok(Self::new().start(char_to_int(value)? as u64))
	}
}

#[cfg(test)]
mod test {
	use super::*;

	/// Test violations of the max_render_capacity system, ensure we return an error
	fn max_render_capacity() {
		// Test link between max_alpha(chars) and the OutOfRange
		for limit in 1..10 {
			let max = crate::sequence::renderer::max_alpha(limit);
			let mut seq = SequenceBuilder::new().start(max)
				.upper()
				.max_render_capacity(limit)
				.build()
				.unwrap();
			let render_as = "Z".repeat(limit as usize);
			let elem = seq.next().unwrap();
			assert_eq!( elem.to_string(), render_as );
			let elem = seq.next();
			assert_eq!( elem, None );
			assert_eq!( seq.next(), None )
		}

		// Test max_numeric(chars) + 1 throws OutOfRange
		for limit in 1..10 {
			let max = crate::sequence::renderer::max_numeric(limit);
			let mut seq = SequenceBuilder::new().start(max).numeric().max_render_capacity(limit).build().unwrap();
			let render_as = "9".repeat(limit as usize);
			assert_eq!( seq.to_string(), render_as, "Render {} as {}", max, render_as );
			assert_eq!(
				seq.next(),
				None,
				"Throw error with numeric char limit of {} which can only represent {}",
					limit,
					max
			);
			assert_eq!( seq.next(), None )
		}
	}

	/// Test that the first element renders properly with .upper() .lower() and .numeric()
	#[test]
	fn simple() {
		for c in 'A'..'Z' {
			// upper
			let mut seq = SequenceBuilder::new().start(c as u64 - 'A' as u64).upper().build().unwrap();
			let elem = seq.next().unwrap();
			assert_eq!(
				elem.to_string(),
				c.to_string(),
			);

			// lower
			let mut seq = SequenceBuilder::new().start(c as u64 - 'A' as u64).lower().build().unwrap();
			let elem = seq.next().unwrap();
			assert_eq!(
				elem.to_string(),
				c.to_string().to_lowercase(),
			);
		}

		// numeric
		for i in 1..123_456 {
			let mut seq = SequenceBuilder::new().start(i).numeric().build().unwrap();
			let elem = seq.next().unwrap();
			assert_eq!(
				elem.to_string(),
				i.to_string()
			);
		}
	}

	fn rollover() {
		const A: u32  = 0;
		const Z: u32 = 25;
		for i in A..Z {

			// Easy check for A[A-Z] after Z
			let seq = SequenceBuilder::new().start(Z as u64).upper().build().unwrap();
			let result = format!("A{}", std::char::from_u32('A' as u32 + i).unwrap());
			assert_eq!(
				seq.skip(i as usize + 1).next().unwrap().to_string(),
				result
			);
			
			let mut seq = SequenceBuilder::new().start(Z as u64).upper().build().unwrap();
			assert_eq!(
				seq.nth(i as usize + 1).unwrap().to_string(),
				result,
				".nth({})", i
			);

			let seq = SequenceBuilder::new().start(Z as u64 + 1 + i as u64).lower().build().unwrap();
			assert_eq!(
				seq.to_string(),
				result.to_lowercase()
			);
			
			let mut seq = SequenceBuilder::new().start(A as u64).upper().build().unwrap();
			for len in 1..5 {
				assert_eq!(
					seq.nth(26usize.pow(len as u32) - 1).unwrap().to_string(),
					"A".repeat(len + 1),
				);
			}
			
			let mut seq = SequenceBuilder::new().start(Z as u64).upper().build().unwrap();
			for len in 2..5 {
				assert_eq!(
					seq.nth(26usize.pow(len as u32) - 1).unwrap().to_string(),
					"Z".repeat(len),
				);
			}
		}
	}

}