#MaxStack (Dual-Stack Implementation)

#🚀 Core Features

#📥 Installation

moon add SupremeHuaji/MaxStack

#🚀 Usage Guide

#🔨 Creating a MaxStack

  // Create a new empty stack
  let stack = @MaxStack.new()

  // Create type-specific stacks using generics
  let int_stack : MaxStack[Int] = @MaxStack.new()
  let string_stack : MaxStack[String] = @MaxStack.new()

#➕ Adding Elements

  let stack = @MaxStack.new()
    .push(10)
    .push(5)
    .push(20)
    .push(15)

  // Stack now contains: [10, 5, 20, 15] (bottom to top)

#🔍 Viewing Top Element

  let stack = @MaxStack.new()
    .push(10)
    .push(20)

  match stack.peek() {
    Ok(value) => println("Top element: \{value}")  // Output: Top element: 20
    Err(StackError::EmptyStack) => println("Stack is empty")
  }

#❌ Removing Elements

  let stack = @MaxStack.new()
    .push(10)
    .push(20)

  match stack.pop() {
    Ok((value, new_stack)) => {
      println("Popped element: \{value}")  // Output: Popped element: 20
      // new_stack is the stack after removing the element
    }
    Err(StackError::EmptyStack) => println("Stack is empty, cannot pop")
  }

#🔝 Getting Maximum Value

  let stack = @MaxStack.new()
    .push(10)
    .push(5)
    .push(20)
    .push(15)

  match stack.get_max() {
    Ok(max_value) => println("Maximum in stack: \{max_value}")  // Output: Maximum in stack: 20
    Err(StackError::EmptyStack) => println("Stack is empty, no maximum")
  }

#📏 Checking Stack Status

  let stack = @MaxStack.new()
    .push(10)
    .push(20)

  // Check if stack is empty
  if stack.is_empty() {
    println("Stack is empty")
  } else {
    println("Stack is not empty")
  }

  // Get stack size
  let size = stack.size()
  println("Stack size: \{size}")  // Output: Stack size: 2

#🧠 Generic Support

  // Integer stack
  let int_stack = @MaxStack.new()
    .push(100)
    .push(50)
    .push(200)

  // Float stack  
  let float_stack = @MaxStack.new()
    .push(10.5)
    .push(20.3)
    .push(15.7)

  // String stack (lexicographic comparison)
  let string_stack = @MaxStack.new()
    .push("apple")
    .push("banana")
    .push("cherry")

#🔄 Method Chaining

  let result = @MaxStack.new()
    .push(10)
    .push(5)
    .push(20)
    .push(15)

  match result.get_max() {
    Ok(max) => println("Maximum: \{max}")  // Output: Maximum: 20
    Err(_) => println("Operation failed")
  }

  // Consecutive pop operations
  let stack = @MaxStack.new()
    .push(10)
    .push(20)
    .push(30)

  match stack.pop() {
    Ok((value1, stack1)) => {
      println("First pop: \{value1}")  // Output: First pop: 30
      match stack1.pop() {
        Ok((value2, stack2)) => {
          println("Second pop: \{value2}")  // Output: Second pop: 20
          match stack2.get_max() {
            Ok(max) => println("Remaining maximum: \{max}")  // Output: Remaining maximum: 10
            Err(_) => println("Stack is empty")
          }
        }
        Err(_) => println("Second pop failed")
      }
    }
    Err(_) => println("First pop failed")
  }

#⚠️ Error Handling

  let empty_stack = @MaxStack.new()

  // Operations on empty stack will return errors
  match empty_stack.peek() {
    Ok(value) => println("Top: \{value}")
    Err(StackError::EmptyStack) => println("Error: Attempting to peek empty stack")
  }

  match empty_stack.pop() {
    Ok((value, new_stack)) => println("Popped: \{value}")
    Err(StackError::EmptyStack) => println("Error: Attempting to pop from empty stack")
  }

  match empty_stack.get_max() {
    Ok(max) => println("Maximum: \{max}")
    Err(StackError::EmptyStack) => println("Error: Attempting to get maximum from empty stack")
  }

#🚀 Performance Tips & Best Practices

  // ✅ Good: Use method chaining for batch operations
  let efficient_stack = @MaxStack.new()
    .push(10)
    .push(20)
    .push(5)
    .push(30)

  // ✅ Good: Properly handle error cases
  match stack.pop() {
    Ok((value, new_stack)) => {
      // Use value and new_stack for subsequent operations
      process_value(value)
      continue_with_stack(new_stack)
    }
    Err(StackError::EmptyStack) => {
      // Handle empty stack case
      handle_empty_stack()
    }
  }

  // ✅ Good: Leverage O(1) maximum value query advantage
  let stack = build_large_stack()
  match stack.get_max() {
    Ok(max) => println("Quickly found maximum in large stack: \{max}")
    Err(_) => println("Stack is empty")
  }

#🔧 Implementation Principle

#Core Algorithm Idea:

1. Push Operation: Push element to main stack, push current maximum to auxiliary stack
2. Pop Operation: Pop elements from both stacks simultaneously
3. GetMax Operation: Directly return top element from auxiliary stack

#📋 Complete API Reference

#Constructor Methods

#Core Operations

#Query Operations

#Error Types

#⏱️ Time Complexity Summary

#📜 License

#📢 Contact & Support