<?php

/*
Script: gapi_tools.inc
	Basic tools

License:
	MIT-style license.

Version:
	v0.3

GAPI Copyright:
	copyright (c) 2007 Gregory Koberger <http://www.gkoberger.net>

ToDo:

  - Add JSON support to toArray
  - Add toArray support to everything
*/

  /*
     Class: gapiTools
     A class that contains basic tools
  */

  class gapiTools
  {

    /*
       Function: convertArray

       Turns keys with no value into a key rather than a value

       Parameters:

          $array - The array to be converted

       Examples:

         | $array = array( value1 => 'Value 1', value2 , value3 => 3);
         | print_r( $array );
         |
         | // Returns:
         | // Array
         | // (
         | //     [value1] => Value 1
         | //     [0] => value2
         | //     [value3] => 3
         | // )
         |
         | $arrayNew = $gapi_tools->convertArray( $array );
         |
         | // Returns:
         | // Array
         | // (
         | //     [value1] => Value 1
         | //     [value2] => true
         | //     [value3] => 3
         | // )

       Returns:

          A converted array

    */

    function convertArray( $array )
    {

      settype($array, "array");

      foreach($array as $k=>$v)
      {

        unset($array[ $k ]);

        if( is_numeric( $k ) )
          $array[ $v ] = true;
        else
          $array[ $k ] = $v;
      }

      return $array;

    }

    /*
       Function: toArray

       Converts strings and JSON (PHP 5.2.0+ only) into arrays.

       *Note:* Arrays are accepted, and are returned untouched.  This function is used for if you want to accept both strings and arrays.

       Parameters:

          $input - The input or string to be converted

       Examples:

         | $arrayNew = gapiTools::toArray( "Test String" );
         |
         | // Returns:
         | // Array
         | // (
         | //     [0] => 'Test String'
         | // )

       Returns:

          An array

    */

    function toArray( $input )
    {

      if(is_array( $input ))
        return $input;
      else
        return array( $input );
    }

    /*
       Function: getFirst

       Returns the first element of an array

       Functions much like array_shift, without modifying the original array

       Parameters:

          $array - The array to be converted

       Examples:

         | $first = gapiTools::getFirst( array( 'a'=>'apple', 'b'=> 'boy' );
         |
         | // Returns:
         | // apple

       Returns:

          The first element of the array (as a string)

    */

    function getFirst( $array )
    {

      $a = gapiTools::toArray( $array );

      return array_shift( $a );

    }

    /*
       Function: getLast

       Returns the last element of an array

       Parameters:

          $array - The array to be converted

       Examples:

         | $first = gapiTools::getFirst( array( 'a'=>'apple', 'b'=> 'boy' );
         |
         | // Returns:
         | // boy

       Returns:

          The last element of the array (as a string)
    */

    function getLast( $array )
    {

      $a = array_reverse( gapiTools::toArray( $array ) );

      return array_shift( $a );

    }

  }


?>