---

Mastering Crystal Collections: The Ultimate High Score Leaderboard Guide

Learn to manage a high score list in Crystal by implementing methods to find the highest score, retrieve the last added score, and select the top three scores. This guide dives deep into Crystal's powerful array manipulation, sorting capabilities, and object-oriented design, turning a classic programming challenge into a practical skill.

Remember the thrill of seeing your initials at the top of an arcade machine? That blinking, three-letter testament to your skill was more than just a score; it was a badge of honor. Behind that simple leaderboard lies a fundamental programming challenge: how do you efficiently manage, sort, and display a list of scores? You've likely faced this problem, whether in game development, data analysis, or simple list management, and felt the friction of getting it just right.

This guide is your solution. We will transform this classic problem into a learning opportunity, using the elegant and powerful Crystal programming language. We'll build a robust HighScores component from scratch, exploring the core concepts that power data manipulation in modern software. By the end, you won't just have a solution; you'll have a deeper understanding of Crystal's collections API and a reusable pattern for any leaderboard-style application.

---

What is the High Score Management Problem?

At its heart, the High Score challenge, a core module from the exclusive kodikra.com learning curriculum, is about data retrieval and manipulation. It simulates a common requirement in applications where a series of numerical data points (like game scores) needs to be queried in different ways. The goal is to build a class or module that can take a list of scores and perform specific, common operations on it.

The primary requirements are straightforward:

• Accept a List: The component must be initialized with an existing list of scores.
• Report the Latest Score: It needs a method to return the most recently added score.
• Identify the Personal Best: It must be able to find and return the single highest score from the list.
• List the Top Three: It needs a method to return a new list containing the three highest scores, in descending order.

This problem is a perfect vehicle for learning fundamental programming concepts because it directly involves array handling, sorting algorithms, and basic object-oriented design. It forces you to think about data immutability (should sorting the "top three" change the original list?) and efficiency (is there a better way than re-sorting every time?).

---

Why Crystal is the Perfect Tool for the Job

While you could solve this problem in any language, Crystal offers a unique blend of developer-friendly syntax and high performance, making it an ideal choice. Its standard library is rich and expressive, allowing for clean, readable solutions that are also incredibly fast.

For this specific task, Crystal's strengths shine through:

• Expressive Enumerable Module: Crystal inherits a beautiful, chainable API for collections from Ruby. Methods like max, sort, reverse, and first allow you to write code that reads almost like plain English.
• Static Typing with Type Inference: Crystal is statically typed, which catches errors at compile time, but you rarely have to write the types yourself. It knows that a list of [10, 30, 20] is an Array(Int32), giving you safety without sacrificing speed of development.
• Compiled Performance: Under the hood, Crystal compiles down to highly efficient native code via LLVM. This means your elegant, readable code runs with speeds comparable to C or C++, making it suitable for performance-critical applications like game backends.
• Object-Oriented Purity: Creating a HighScores class is natural and clean in Crystal. Encapsulating the scores and the logic to operate on them within a single object is a core tenet of good software design, which Crystal makes effortless.

By tackling this problem in Crystal, you're not just learning to manipulate arrays; you're learning to leverage a modern, powerful language to write code that is both beautiful and blazingly fast. To explore more about the language, check out our complete Crystal language guide.

---

How to Build the High Score Component in Crystal: The Complete Solution

Let's dive into the code. Our goal is to create a HighScores class that encapsulates the list of scores and provides methods to query it. This approach follows best practices by keeping the data (the scores) and the operations on that data bundled together.

Here is the complete, well-commented solution. We will break it down piece by piece in the following section.

# Manages a list of game scores, providing methods to query them.
class HighScores
  # The list of scores is stored in an instance variable.
  # The type annotation `Array(Int32)` ensures we only store 32-bit integers.
  @scores : Array(Int32)

  # The constructor, called when a new HighScores object is created.
  # It takes an array of scores as input and assigns it to the instance variable.
  def initialize(@scores)
  end

  # Returns the full list of scores.
  # This is a "getter" method that Crystal creates automatically for @scores.
  getter scores

  # Returns the last score that was added to the list.
  # The `last` method on Array is efficient for this operation.
  def last
    @scores.last
  end

  # Returns the highest score from the list.
  # The `max` method from the Enumerable module finds the maximum value.
  def personal_best
    @scores.max
  end

  # Returns a new array containing the top three scores, sorted from highest to lowest.
  # This method does not modify the original @scores array.
  def top_three
    # 1. Sort the array in ascending order (e.g., [10, 30, 90] -> [10, 30, 90])
    # 2. Reverse the sorted array to get descending order ([10, 30, 90] -> [90, 30, 10])
    # 3. Take the first 3 elements from the reversed array.
    @scores.sort.reverse.first(3)
  end
end

This implementation is concise yet powerful. It leverages Crystal's standard library effectively, resulting in code that is easy to read, understand, and maintain. The use of an instance variable @scores ensures that each instance of HighScores maintains its own state, independent of others.

---

Deep Dive: A Step-by-Step Code Walkthrough

Understanding the code is more than just reading it. Let's dissect each part of the HighScores class to understand the underlying concepts and Crystal-specific features.

The Class Definition and Constructor

class HighScores ... end defines our blueprint. Inside, @scores : Array(Int32) declares an instance variable. The @ prefix signifies that it belongs to an instance of the class, not just a local method. The type annotation : Array(Int32) is a promise to the compiler that this variable will always hold an array of 32-bit integers, which helps prevent bugs.

The initialize method is the constructor. The line def initialize(@scores) is a fantastic piece of Crystal shorthand. It automatically does three things:

1. Defines an initialize method that accepts one argument named scores.
2. Declares an instance variable named @scores.
3. Assigns the passed argument to the @scores instance variable.

Getter for Scores

The line getter scores is another Crystal macro that saves typing. It automatically generates a method named scores that simply returns the value of the @scores instance variable. This allows external code to read the list of scores (e.g., my_scores.scores) without being able to modify it directly.

Fetching the Last Score: def last

This method is simple but demonstrates the power of Crystal's core library. The Array#last method is highly optimized to retrieve the final element of an array. It's more readable and potentially more performant than using manual indexing like @scores[@scores.size - 1], especially as it gracefully handles empty arrays by returning nil.

Finding the Personal Best: def personal_best

Here, we use the Enumerable#max method. Since Array includes the Enumerable module, it gets access to a wealth of powerful iteration and querying methods. @scores.max iterates through the entire list and returns the single greatest value. This is a declarative approach—we state what we want (the maximum), not how to find it (looping and comparing).

The Top Three Logic: def top_three

This is the most interesting method. It's a chain of three distinct operations, showcasing the fluent interface of Crystal's collections.

@scores.sort.reverse.first(3)

Let's visualize this flow:

 ● Input: @scores = [100, 0, 90, 30]
 │
 ▼
┌────────────────┐
│ @scores.sort() │  Sorts in ascending order
└───────┬────────┘
        │
        ▼
 ● Result: [0, 30, 90, 100]
 │
 ▼
┌──────────────────┐
│ .reverse()       │  Reverses the sorted array
└─────────┬────────┘
          │
          ▼
 ● Result: [100, 90, 30, 0]
 │
 ▼
┌──────────────────┐
│ .first(3)        │  Takes the first N elements
└─────────┬────────┘
          │
          ▼
 ● Final Output: [100, 90, 30]

An important detail is that sort returns a new sorted array, leaving the original @scores array unmodified. This is crucial for maintaining the integrity of our original data, ensuring that the order in which scores were added is preserved.

---

Alternative Approaches and Performance Trade-offs

The provided solution is clean and correct, but it's not the only way. In software engineering, every choice has trade-offs. Let's explore an alternative and compare it.

Alternative: Sort on Initialization

If we anticipate calling top_three or personal_best very frequently, sorting the array every single time might seem inefficient. An alternative is to pre-process the data. We could store a sorted version of the scores upon initialization.

class HighScoresOptimized
  @scores : Array(Int32)
  @sorted_scores : Array(Int32)

  def initialize(@scores)
    # Sort once and store the result
    @sorted_scores = @scores.sort.reverse
  end

  def last
    @scores.last # Still need the original for this
  end

  def personal_best
    # Now this is very fast, just grab the first element
    @sorted_scores.first
  end

  def top_three
    # Also very fast, just take a slice
    @sorted_scores.first(3)
  end
end

This approach changes the performance characteristics of our class. Let's analyze the pros and cons.

Aspect	Original Approach (Sort on Demand)	Alternative (Sort on Init)
Initialization Speed	Very fast. Just an array assignment.	Slower. Requires a full sort operation (O(n log n)).
Memory Usage	Lower. Stores only one copy of the scores.	Higher. Stores two copies of the scores (original and sorted).
personal_best / top_three Speed	Slower. Requires sorting on each call.	Extremely fast. Simple array access (O(1) or O(k)).
Use Case	Best for "write-heavy" or "infrequent-read" scenarios.	Best for "read-heavy" scenarios where top scores are queried often.

Choosing between them depends on the application's specific needs. For a typical game leaderboard where scores are added often but the top list is viewed less frequently, the original approach is perfectly fine. For a data analysis tool that constantly queries the top values, the optimized approach would be superior.

---

Where to Apply These Concepts: A Practical Example

Now that we have our HighScores class, let's see how to use it in a real Crystal application. We'll create a simple program that instantiates the class and prints out the results.

Create a file named main.cr:

# First, we need to include the file containing our class definition.
require "./high_scores.cr"

# Let's define a set of scores from a fictional game session.
player_scores = [340, 120, 500, 410, 390, 1000, 750]

# Create a new instance of our HighScores class.
leaderboard = HighScores.new(player_scores)

# Now, let's use the methods we created.
puts "--- Player Score Analysis ---"
puts "All scores recorded: #{leaderboard.scores}"
puts "The last score added was: #{leaderboard.last}"
puts "The player's personal best is: #{leaderboard.personal_best}"
puts "The top three high scores are: #{leaderboard.top_three}"

# What happens with a smaller list?
short_list = HighScores.new([50, 20])
puts "\n--- Analysis for a shorter list ---"
puts "Top three scores: #{short_list.top_three}" # Should handle this gracefully

Assuming your HighScores class is in a file named high_scores.cr in the same directory, you can compile and run this program from your terminal.

Terminal Commands:

1. Compile the code: The crystal build command compiles your application into a native executable. The --release flag enables optimizations for better performance.

   crystal build main.cr --release

2. Run the executable: This will execute your compiled program.

   ./main

Expected Output:

--- Player Score Analysis ---
All scores recorded: [340, 120, 500, 410, 390, 1000, 750]
The last score added was: 750
The player's personal best is: 1000
The top three high scores are: [1000, 750, 500]

--- Analysis for a shorter list ---
Top three scores: [50, 20]

This simple example demonstrates the complete lifecycle: defining data, instantiating an object, calling its methods, and displaying the results. This pattern is the foundation of countless applications.

Here is a visualization of the application's overall logic flow:

    ● Start
    │
    ▼
  ┌─────────────────────────┐
  │ Define `player_scores`  │
  │ Array: [340, 120, ...]  │
  └────────────┬────────────┘
               │
               ▼
  ┌─────────────────────────┐
  │ `leaderboard =`         │
  │ `  HighScores.new(...)` │
  └────────────┬────────────┘
               │
               ▼
  ◆ Call Methods on `leaderboard`
  ├───────────────────────────
  │
  ├───> .last() ───────────> 750
  │
  ├───> .personal_best() ──> 1000
  │
  └───> .top_three() ──────> [1000, 750, 500]
               │
               ▼
  ┌─────────────────────────┐
  │ Print Results to Console│
  └────────────┬────────────┘
               │
               ▼
    ● End

---

Frequently Asked Questions (FAQ)

What happens if the list of scores is empty when I call these methods?

Crystal's standard library handles this gracefully. [].last and [].max will both return nil, which represents the absence of a value. [].sort.reverse.first(3) will simply return an empty array []. Your code should be prepared to handle nil values if an empty list is a possibility.

How does Crystal's sort method work internally?

Crystal's Array#sort uses a highly efficient hybrid sorting algorithm called Timsort. It's the same algorithm used by default in Python and Java. Timsort performs exceptionally well on many kinds of real-world data, combining the best of merge sort and insertion sort.

Is the chain sort.reverse.first(3) efficient?

Yes, it is generally very efficient for moderately sized arrays. While it creates intermediate arrays, Crystal's compiler is good at optimizing, and the operations themselves are fast. For extremely large datasets (millions of scores) queried constantly, you might consider a more specialized data structure like a max-heap, but for most applications, this approach is the perfect balance of readability and performance.

What's the difference between .first(3) and a slice like [0, 3]?

Functionally, they often produce the same result. .first(3) is arguably more readable as it clearly states the intent of getting the "first N" items. It also handles cases where the array has fewer than 3 elements without error, whereas a slice like [0...3] would work fine too. The first(n) method is often preferred for its clarity.

Why use an instance variable @scores instead of a local variable?

An instance variable (@scores) stores state that persists for the lifetime of the object. A local variable (scores) only exists within the scope of a single method call. By using an instance variable, we can pass the scores to the object once during initialization and then call multiple methods (last, personal_best) on that same data without needing to pass it in every time.

How would this code handle duplicate high scores?

The current implementation handles duplicates correctly. If the scores were [100, 90, 90, 80], top_three would return [100, 90, 90]. The sort method maintains the relative order of equal elements, and first(3) simply takes the first three elements of the sorted list, duplicates included.

Can I adapt this logic for non-numeric data, like player names with scores?

Absolutely. You would typically use an array of custom objects or structs, for example, Array(PlayerScore) where PlayerScore has name : String and score : Int32 attributes. You would then provide a block to the sort method to specify how to compare two PlayerScore objects, like scores.sort_by(&.score).reverse.

---

Conclusion: From Scores to Skills

We've successfully built a complete, practical, and efficient HighScores component in Crystal. What started as a simple problem—managing a list of numbers—unlocked a tour of fundamental software development concepts: object-oriented design, data encapsulation, algorithm efficiency, and the power of a well-designed standard library.

You learned how to leverage Crystal's expressive syntax to chain methods like sort, reverse, and first to create powerful, readable one-liners. We explored the trade-offs between different implementation strategies, a critical skill for any developer aiming to write high-performance code. Most importantly, you now have a reusable pattern that can be adapted for leaderboards, data analysis, or any scenario requiring the querying of ordered data.

This exercise from the kodikra learning path is a stepping stone. The principles you've applied here are universal, and mastering them in a language as elegant and performant as Crystal will undoubtedly accelerate your journey as a developer. Keep exploring, keep building, and keep climbing that leaderboard.

Disclaimer: All code examples are written for Crystal 1.12+ and are expected to be compatible with future stable versions. The fundamental concepts discussed are stable features of the language.

---

Published by Kodikra — Your trusted Crystal learning resource.