notebooks/Arrays.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Arrays in Ruby\n",
    "\n",
    "An `Array` is just a list of items in order (like mangoes, apples, and oranges).\n",
    "\n",
    "Every slot in the list acts like a variable: you can see what object a particular slot points to, and you can _make it point to a different object_.\n",
    "\n",
    "You can make an array by using square brackets. In Ruby, the first value in an array has index 0. The `size` and `length` methods return the number of elements in an array. The last element of the array is at index `size-1`. Negative index values count from the end of the array, so the last element of an array can also be accessed with an index of `-1`.\n",
    "\n",
    "If you attempt to read an element beyond the end of an array (with an index `>= size`) or before the beginning of an array (with an index `< -size`), Ruby simply returns `nil` and does not throw an exception.\n",
    "\n",
    "Ruby's arrays are mutable - arrays are dynamically resizable; you can append elements to them and they grow as needed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Table of Contents\n",
    "\n",
    "  - [Parallel Assignment](#Parallel-Assignment)\n",
    "  - [Environment Variables](#Environment-Variables)\n",
    "  - [Command-line Arguments](#Command-line-Arguments)\n",
    "  - [Library GetoptLong](#Library-GetoptLong)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "# Empty array\n",
    "var = []\n",
    "\n",
    "# Array index starts from 0\n",
    "puts var[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5\n"
     ]
    }
   ],
   "source": [
    "# An array holding a single number\n",
    "var = [5]\n",
    "puts var[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n",
      "Goodbye\n"
     ]
    }
   ],
   "source": [
    "# An array holding two strings\n",
    "var = %w{ Hello Goodbye }\n",
    "puts var[0]\n",
    "puts var[1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[true, false]\n"
     ]
    }
   ],
   "source": [
    "flavour = 'mango'\n",
    "# An array whose elements are pointing to three objetcs\n",
    "# a float, a string and an array\n",
    "var = [80.5, flavour, [true, false]]\n",
    "puts var[2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cris\n",
      "Fran\n",
      "Kevin\n",
      "Imanol\n",
      "\n",
      "Alberto\n",
      "4.33\n",
      "[1, 2, 3]\n"
     ]
    }
   ],
   "source": [
    "# A trailing comma is ignored\n",
    "var = ['Cris', 'Fran', 'Kevin', 'Imanol',]\n",
    "puts var[0]\n",
    "puts var[1]\n",
    "puts var[2]\n",
    "puts var[3]\n",
    "\n",
    "# The next one outputs nil\n",
    "# nil is Ruby's way of saying nothing\n",
    "puts var[4]\n",
    "\n",
    "# We can add more elements too\n",
    "var[4] = 'Alberto'\n",
    "puts var[4]\n",
    "\n",
    "# We can add anything!\n",
    "var[5] = 4.33\n",
    "puts var[5]\n",
    "\n",
    "# We can add an array to an array\n",
    "var[6] = [1, 2, 3]\n",
    "puts var[6]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1, 23, 45, 90]\n",
      "4\n",
      "45\n",
      "90\n"
     ]
    }
   ],
   "source": [
    "# Some basic methods on arrays\n",
    "arr = [45, 23, 1, 90]\n",
    "puts arr.sort\n",
    "puts arr.length\n",
    "puts arr.first\n",
    "puts arr.last"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Method `each` (iterator) - Extracts each element into `loc`.\n",
    "- `do/end` is a block of code (see [Blocks notebook](Blocks.ipynb))\n",
    "- Variable `loc` refers to each item in the array as it goes through the loop."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "I love Cuenca!\n",
      "Don't you?\n",
      "I love Menorca!\n",
      "Don't you?\n",
      "I love Florence!\n",
      "Don't you?\n",
      "I love Vernazza!\n",
      "Don't you?\n",
      "---\n",
      "I love Cuenca!\n",
      "Don't you?\n",
      "I love Menorca!\n",
      "Don't you?\n",
      "I love Vernazza!\n",
      "Don't you?\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "[\"Cuenca\", \"Menorca\", \"Vernazza\"]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "locations = %w{ Cuenca Menorca Florence Vernazza }\n",
    "locations.each do |loc|\n",
    "  puts \"I love #{loc}!\"\n",
    "  puts \"Don't you?\"\n",
    "end\n",
    "\n",
    "puts '---'\n",
    "\n",
    "# Delete an entry in the middle and shift the remaining entries\n",
    "locations.delete('Florence')\n",
    "locations.each do |loc|\n",
    "  puts \"I love #{loc}!\"\n",
    "  puts \"Don't you?\"\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method `each` (for any object) allows us to do something (whatever we want) to each object the array points to.\n",
    "\n",
    "In the example, we are able to go through each object in the array without using any numbers. Here are a few things to remember:\n",
    "\n",
    "  - The variable `loc` inside the \"goalposts\" refers to each item in the array as it goes through the loop. You can give this any name you want, but make it memorable.\n",
    "  - The `do` and `end` identify a block of code that will be executed for each item. Blocks are used extensively in Ruby.\n",
    "  \n",
    "Here's an interesting example of a method that returns an array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "6\n",
      "36\n"
     ]
    }
   ],
   "source": [
    "# If you give return multiple parameters, the method returns them in an array\n",
    "# The times method of the Integer class iterates block num times, passing in values from zero to num-1\n",
    "\n",
    "def mtdarry\n",
    "  10.times do |num|\n",
    "    square = num * num\n",
    "    return num, square if num > 5\n",
    "  end\n",
    "end\n",
    "\n",
    "# Using parallel assignment to collect the return value\n",
    "num, square = mtdarry\n",
    "puts num\n",
    "puts square"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `times` method of the `Integer` class iterates block num times, passing in values from zero to num-1. As we can see, if you give `return` multiple parameters, the method returns them in an array. You can use parallel assignment to collect this return value."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parallel Assignment\n",
    "\n",
    "To explain this, we'll use the terms _lvalue_ and _rvalue_.\n",
    "\n",
    "  - An _lvalue_ is something that can appear on its own on the left-hand side of an assignment (a variable, a constant, or _**attribute setter method**_).\n",
    "  - An _rvalue_ is something that can appear on its own on the right hand side.\n",
    "\n",
    "Ruby lets you have a comma-separated list of rvalues. Once Ruby sees more than one rvalue in an assignment, the rules of parallel assignment come into play. First, all the rvalues evaluated, left to right, and collected into an array (unless they are already an array). This array will be the eventual value returned by the overall assignment. Next, the left hand side (lhs) is inspected. If it contains a single element, the array is assigned to that element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "a = 1, 2, 3, 4   # => a == [1, 2, 3, 4]\n",
    "b = [1, 2, 3, 4] # => b == [1, 2, 3, 4]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the _lhs_ contains a comma, Ruby matches values on the _rhs_ against successive elements on the _lhs_. Excess elements are discarded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "a, b = 1, 2, 3, 4 # => a == 1, b == 2\n",
    "c, = 1, 2, 3, 4   # => c == 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Environment Variables\n",
    "\n",
    "An environment variable is a link between our programm and the outside world. An environment variable is essentially a label referring to a piece of text; and can be used to store configuration information such as paths, usernames, and so on.\n",
    "\n",
    "You can access operating system environment variables using the predefined variable `ENV`. `ENV` is simply a hash."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "PWD: /Users/Carlos/Documents/Projects/github/ruby-notebooks\n",
      "SHELL: /usr/local/bin/zsh\n",
      "LC_CTYPE: UTF-8\n",
      "TERM_PROGRAM_VERSION: 3.4.4\n",
      "TERM_PROGRAM: iTerm.app\n",
      "PATH: /usr/local/lib/ruby/gems/3.0.0/bin:/usr/local/opt/ruby/bin:/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Applications/VMware Fusion.app/Contents/Public:/Library/Apple/usr/bin\n",
      "LC_TERMINAL: iTerm2\n",
      "COLORTERM: truecolor\n",
      "TERM: xterm-256color\n",
      "HOME: /Users/Carlos\n",
      "USER: Carlos\n",
      "LANG: en_US.UTF-8\n",
      "LC_ALL: en_US.UTF-8\n",
      "EDITOR: vimr --wait\n",
      "PAGER: less\n",
      "LESS: -R\n",
      "BUNDLER_ORIG_BUNDLE_BIN_PATH: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_BUNDLE_GEMFILE: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_BUNDLER_VERSION: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_GEM_HOME: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_GEM_PATH: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_MANPATH: /usr/local/share/man::\n",
      "BUNDLER_ORIG_PATH: /usr/local/lib/ruby/gems/3.0.0/bin:/usr/local/opt/ruby/bin:/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Applications/VMware Fusion.app/Contents/Public:/Library/Apple/usr/bin\n",
      "BUNDLER_ORIG_RB_USER_INSTALL: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_RUBYLIB: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "BUNDLER_ORIG_RUBYOPT: BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL\n",
      "GEM_PATH: /usr/local/lib/ruby/gems/3.0.0:/Users/Carlos/.local/share/gem/ruby/3.0.0:/usr/local/Cellar/ruby/3.0.0_1/lib/ruby/gems/3.0.0\n"
     ]
    }
   ],
   "source": [
    "ENV.each {|k,v| puts \"#{k}: #{v}\"}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ruby sets `ENV` to the environment variables. After that, iteration proceeds with `each`. This time, the block takes two parameters: `k` (key) and `v` (value). Blocks are a completely general mechanism and can take any number of arguments.\n",
    "\n",
    "The values of some environment variables are read by Ruby when it first starts. These variables modify the behaviour of the interpreter, as shown below.\n",
    "\n",
    "|Variable Name|Description|\n",
    "|------------:|:----------|\n",
    "|`DLN_LIBRARY_PATH`|Search path for dynamically loaded modules.|\n",
    "|`HOME`|Points to user's home directory. Used when expanding `~` in file and directory names.|\n",
    "|`LOGDIR`|Fallback pointer to the user's home directory if `$HOME` is not set. Used only by `Dir.chdir`.|\n",
    "|`OPENSSL_CONF`|Specify location of OpenSSL configuration file.|\n",
    "|`RUBYLIB`|Additional search path for Ruby programs (`$SAFE` must be 0).|\n",
    "|`RUBYLIB_PREFIX`|(Windows only) Mangle the `RUBYLIB` search path by adding this prefix to each component.|\n",
    "|`RUBYOPT`|Additional command-line options to Ruby; examined after real command-line options are parsed (`$SAFE` must be 0).|\n",
    "|`RUBYPATH`|With `-S` option, search path for Ruby programs (defaults to `PATH`).|\n",
    "|`RUBYSHELL`|Shell to use when spawning a process under Windows; if not set, will also chech `SHELL` or `COMSPEC`.|\n",
    "|`RUBY_TCL_DLL`|Override default name for TCL shared library or DLL.|\n",
    "|`RUBY_TK_DLL`|Override default name for TK shared library or DLL. Both this and `RUBY_TCL_DLL` must be set for either to be used.|\n",
    "\n",
    "A Ruby program may write to the `ENV` object. On most systems this changes the values of the corresponding environment variables. However, this change is local to the process that makes it and to any subsequently spawned child process. A subprocess changes an environment variable, and this change is inherited by a process that it then starts. However, the change is not visible to the original parent. (This just goes to prove that parents never really know what their children are doing.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "FORMAC101\n"
     ]
    }
   ],
   "source": [
    "ENV[\"course\"] = \"FORMAC101\"\n",
    "puts \"#{ENV['course']}\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As of Ruby 1.9, setting an environment variable's value to `nil` removes the variable from the environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Command-line Arguments\n",
    "\n",
    "If you're starting a program from the command line, you can append parameters onto the end of the command and the program processes them.\n",
    "\n",
    "You can do the same with your Ruby application. Ruby automatically places any parameters that are appended to the command line when you launch your Ruby program into a special array called `ARGV`. If your program is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = ARGV[0]\n",
    "puts f"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can execute this program from the command line as:\n",
    "\n",
    "```sh\n",
    "ruby tmp.rb 23\n",
    "```\n",
    "\n",
    "The program should display `23`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Library GetoptLong\n",
    "\n",
    "Class `GetoptLong` supports command-line option parsing. Options may be a minus sign (`-`) followed by a single character, or two minus signs (`--`) followed by a name (a long option). Options may be given in any order.\n",
    "\n",
    "A single internal option may have multiple external representations. For example, the option to control verbose output could be any of `-v`, `--verbose`, or `--details`.\n",
    "\n",
    "Some options may also take an associated value. Each internal option is passed to `GetoptLong` as an array, containing strings representating the option's external forms and a flag. The flag specifies how `GetoptLong` is to associate an argument with the option (`NO_ARGUMENT`, `REQUIRED_ARGUMENT`, or `OPTIONAL_ARGUMENT`).\n",
    "\n",
    "Suppose I want to call a Ruby program as:\n",
    "\n",
    "```sh\n",
    "ruby tsftpc.rb -hftp.ibiblio.org -n21 -uanonymous -ps@s.com\n",
    "```\n",
    "\n",
    "Here's the code to do so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Usage: ruby tsftpc.rb -hftp_site_url -nport_no -uuser_name -ppassword\n"
     ]
    }
   ],
   "source": [
    "require 'getoptlong'\n",
    "\n",
    "# Call using \"ruby tsftpc.rb -hftp.ibiblio.org -n21 -uanonymous -ps@s.com\"\n",
    "# The parameters can be in any order\n",
    "unless ARGV.length == 4\n",
    "  puts \"Usage: ruby tsftpc.rb -hftp_site_url -nport_no -uuser_name -ppassword\"\n",
    "  exit\n",
    "end\n",
    "\n",
    "host_name = port_no = user_name = password = ''\n",
    "# Specify the options we accept and initialize the option parser\n",
    "opts = GetoptLong.new(\n",
    "  [ '--hostname', '-h', GetoptLong::REQUIRED_ARGUMENT ],\n",
    "  [ '--port', '-n', GetoptLong::REQUIRED_ARGUMENT ],\n",
    "  [ '--username', '-u', GetoptLong::REQUIRED_ARGUMENT ],\n",
    "  [ '--pass', '-p', GetoptLong::REQUIRED_ARGUMENT ],\n",
    ")\n",
    "\n",
    "# Process the parsed options\n",
    "opts.each do |opt, arg|\n",
    "  case opt\n",
    "    when '--hostname'\n",
    "      host_name = arg\n",
    "    when '--port'\n",
    "      port_no = arg\n",
    "    when '--username'\n",
    "      user_name = arg\n",
    "    when '--pass'\n",
    "      password = arg\n",
    "  end\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### require\n",
    "\n",
    "`require` gives you access to the many extensions and programming libraries bundled with the Ruby programming language-as well as an even larger number of extensions and libraries written independently by other programmers and made available for use with Ruby. We shall be studying `require` in more detail, later on. Also, later on, we shall study how to access `constants` using `::`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How do I convert objects into an Array?\n",
    "\n",
    "If you want to wrap objects in an `Array`, you can use a special `Kernel` module `Array` method (that starts with a capital letter and looks like a class). This special method converts its one argument into an array.\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Array"
     ]
    }
   ],
   "source": [
    "str = 'hello'\n",
    "print Array(str).class"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[\"hello\\\\nworld\"]"
     ]
    }
   ],
   "source": [
    "str = 'hello\\nworld'\n",
    "print Array(str)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Whar are the ancestors of Array?\n",
    "\n",
    "Run the following program, to find that out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[Array, JSON::Ext::Generator::GeneratorMethods::Array, Enumerable, Object, JSON::Ext::Generator::GeneratorMethods::Object, Kernel, BasicObject]"
     ]
    }
   ],
   "source": [
    "a = [1, 2, 3, 4]\n",
    "print a.class.ancestors"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can refer to all the details of the [`Array` class here](http://ruby-doc.org/core-3.0.0/Array.html)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Ruby 3.0.0",
   "language": "ruby",
   "name": "ruby"
  },
  "language_info": {
   "file_extension": ".rb",
   "mimetype": "application/x-ruby",
   "name": "ruby",
   "version": "3.0.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}