اداره‌ی شهر

defmodule String do
  @moduledoc """
  Strings in Elixir are UTF-8 encoded binaries.
  """

  @doc """
  Converts all characters in the given string to uppercase according to `mode`.

  ## Examples

      iex> String.upcase("abcd")
      "ABCD"

      iex> String.upcase("olá")
      "OLÁ"
  """
  def upcase(string, mode \\ :default)
end

@spec longer_than?(String.t(), non_neg_integer()) :: boolean()
def longer_than?(string, length), do: String.length(string) > length

@spec to_hex({hue :: integer, saturation :: integer, lightness :: integer}) :: String.t()

@type color :: {hue :: integer, saturation :: integer, lightness :: integer}

@spec to_hex(color()) :: String.t()

دستورالعمل‌ها

مدتی است که در اداره‌ی شهر کار می‌کنید و مجموعه‌ای از ابزارها را ساخته‌اید که کارهای روزمره‌تان را سرعت می‌بخشند، مثلاً پر کردن فرم‌ها.

حالا همکار تازه‌ای به شما ملحق می‌شود و متوجه شده‌اید که ابزارهایتان ممکن است به‌خودی‌خود روشن و قابل‌فهم نباشند. در اداره‌ی شما رسم‌های عجیب و غریب زیادی وجود دارد؛ مثلاً همیشه فرم‌ها را با حروف بزرگ پر می‌کنند و از خالی گذاشتن فیلدها پرهیز می‌کنند.

تصمیم می‌گیرید مستنداتی بنویسید تا همکار تازه‌تان راحت‌تر وارد کار شود و استفاده از ابزارهایتان را شروع کند.

1. هدف ابزارهای فرم را مستند کنید

به ماژول Form مستنداتی اضافه کنید که هدفش را توصیف کند. متن آن باید این باشد:

A collection of loosely related functions helpful for filling out various forms at the city office.

2. پر کردن فیلدها با مقدارهای خالی را مستند کنید

به تابع Form.blanks/1 مستندات و یک typespec اضافه کنید. مستندات باید این باشد:

Generates a string of a given length.

This string can be used to fill out a form field that is supposed to have no value.
Such fields cannot be left empty because a malicious third party could fill them out with false data.

typespec باید توضیح دهد که تابع یک آرگومان می‌پذیرد، یک عدد صحیح نامنفی، و یک رشته برمی‌گرداند.

3. تقسیم مقدارها به فهرست‌هایی از حروف بزرگ را مستند کنید

به تابع Form.letters/1 مستندات و یک typespec اضافه کنید. مستندات باید این باشد:

Splits the string into a list of uppercase letters.

This is needed for form fields that don't offer a single input for the whole string,
but instead require splitting the string into a predefined number of single-letter inputs.

typespec باید توضیح دهد که تابع یک آرگومان می‌پذیرد، یک رشته، و فهرستی از رشته‌ها برمی‌گرداند.

4. بررسی اینکه آیا یک مقدار در فیلدی با حداکثر طول جا می‌شود را مستند کنید

به تابع Form.check_length/2 مستندات و یک typespec اضافه کنید. مستندات باید این باشد:

Checks if the value has no more than the maximum allowed number of letters.

This is needed to check that the values of fields do not exceed the maximum allowed length.
It also tells you by how much the value exceeds the maximum.

typespec باید توضیح دهد که تابع دو آرگومان می‌پذیرد، یک رشته و یک عدد صحیح نامنفی، و یکی از دو مقدار ممکن را برمی‌گرداند. یا اتم :ok را برمی‌گرداند، یا یک تاپل دوتایی که عنصر اول آن اتم :error است و عنصر دوم یک عدد صحیح مثبت.

5. قالب‌های مختلف آدرس را مستند کنید

به دلیلی که برایتان نامعلوم است، سیستم داخلی اداره‌ی شهر از دو روش متفاوت برای نمایش آدرس‌ها استفاده می‌کند: یا به‌صورت یک مپ یا به‌صورت یک تاپل.

این موضوع را با تعریف سه نوع عمومی سفارشی مستند کنید:

• address_map: یک مپ با کلیدهای :street، :postal_code و :city. هر کلید مقداری از نوع رشته نگه می‌دارد.
• address_tuple: یک تاپل با سه مقدار، street، postal_code و city. هر مقدار از نوع رشته است. مقدارها را با دادن اسم به آن‌ها در typespec از هم متمایز کنید.
• address: می‌تواند یا یک address_map باشد یا یک address_tuple.

6. قالب‌بندی آدرس را مستند کنید

به تابع Form.format_address/1 مستندات و یک typespec اضافه کنید. مستندات باید این باشد:

Formats the address as an uppercase multiline string.

typespec باید توضیح دهد که تابع یک آرگومان می‌پذیرد، یک آدرس، و یک رشته برمی‌گرداند.