Class: Magnitude

• Inheritance
• Description
• Class protocol
  • queries
• Instance protocol
  • Compatibility-Squeak
  • comparing
  • iteration
  • printing
  • testing

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--AbstractChronologyObject
      |
      +--ArithmeticValue
      |
      +--Character
      |
      +--LookupKey
      |
      +--MiniLogger::Severity
      |
      +--SyntaxElement

Package:

stx:libbasic

Category:

Magnitude-General

Version:

rev: 1.44 date: 2023/12/08 08:50:15

user: cg

file: Magnitude.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

This is an abstract class defining common methods for
Objects which can be compared by a kind of less-than relation.

copyright
COPYRIGHT (c) 1988 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 isAbstract

Return if this class is an abstract class.
True is returned for Magnitude here; false for subclasses.
Abstract subclasses must redefine this again.

Instance protocol:

 min: aMin max: aMax

similar to clampBetween:and:

 threeWayCompareWith: arg

alias for compareWith:

 < aMagnitude

Compare the receiver with the argument and return true if the
receiver is less than the argument. Otherwise return false.

** This method must be redefined in concrete classes (subclassResponsibility) **

 <= aMagnitude

return true, if the argument is greater or equal than the receiver

 = aMagnitude

Compare the receiver with the argument and return true if the
receiver is equal to the argument. Otherwise return false.

** This method must be redefined in concrete classes (subclassResponsibility) **

 > aMagnitude

return true, if the argument is less than the receiver

 >= aMagnitude

return true, if the argument is less or equal than the receiver

 clampBetween: min and: max

return the receiver if it is between min .. max,
or min if it is less than min, or max if it is greater than max.
This is only a lazy-typer's helper for: ((something min:max) max:min)

Usage example(s):

1 clampBetween:2 and:5 => 2 3 clampBetween:2 and:5 => 3 6 clampBetween:2 and:5 => 5 2 clampBetween:true and:1 => 1 -- side effect of min not beeing tested (max returned) 1 clampBetween:true and:2 error true clampBetween:1 and:2 error 1 clampBetween:1 and:true error

 compare: arg ifLess: lessBlock ifEqual: equalBlock ifGreater: greaterBlock

three-way compare - thanks to Self for this idea.
Can be redefined in subclasses to do it with a single comparison if
comparison is expensive.

 compareWith: arg

Compare the receiver with the argument and return 1 if the receiver is
greater, 0 if equal and -1 if less than the argument.

Usage example(s):

100 compareWith: 101

 hash

instances, for which #= answers true must answer the same hash

** This method must be redefined in concrete classes (subclassResponsibility) **

 max: aMagnitude

return the receiver or the argument, whichever has greater magnitude

Usage example(s):

1 max: 2 1 max: 2.0 2.0 max: 1.0 2.0 max: 2

 min: aMagnitude

return the receiver or the argument, whichever has lesser magnitude

Usage example(s):

1 min: 2 1 min: 2.0 2.0 min: 1.0 2.0 min: 2

 downTo: stop by: step do: aBlock

For each element of the interval from the receiver down to the argument stop,
decrementing by step, evaluate aBlock, passing the number as argument.

Usage example(s):

10 downTo:1 by:2 do:[:i | Transcript showCR:i].

 downTo: stop by: step doWithExit: aBlock

For each element of the interval from the receiver down to the argument stop,
decrementing by step, evaluate aBlock, passing the number as argument.
aBlock gets another second argument, the exit value.

Usage example(s):

10 downTo:1 by:-1 doWithExit:[:i :exit | i == 5 ifTrue:exit. Transcript showCR:i ].

 downTo: stop do: aBlock

For each element of the interval from the receiver down to the argument stop,
evaluate aBlock, passing the number as argument.

Usage example(s):

10 downTo:1 do:[:i | Transcript showCR:i]. $d downTo:$a do:[:i | Transcript showCR:i].

 downTo: stop doWithExit: aBlock

For each element of the interval from the receiver down to the argument stop,
evaluate aBlock, passing the number as argument.
aBlock gets another second argument, the exit value.

Usage example(s):

10 downTo:1 do:[:i | Transcript showCR:i]. $d downTo:$a do:[:i | Transcript showCR:i].

 to: stop by: incr do: aBlock

For each element of the interval from the receiver up to the argument stop, incrementing
by step, evaluate aBlock passing the element as argument.

Not all Magnitudes do implement #negative and #+ however,
so should this method go to ArithmethicValue?

Only use #<, to speed up things (for subclasses only defining #<)

Usage example(s):

1 to:10 do:[:i | Transcript showCR:i]. 1 to:10 by:2 do:[:i | Transcript showCR:i]. $a to:$z by:2 do:[:i | Transcript showCR:i]. 10 to:1 by:-1 do:[:i | Transcript showCR:i].

 to: stop by: incr doWithBreak: aBlock

For each element of the interval from the receiver up to the argument stop, incrementing
by step, evaluate aBlock passing the element as argument.
Pass a break argument, to allow for premature exit of the loop.

Usage example(s):

1 to:100 by:5 doWithBreak:[:index :break | Transcript showCR:index printString. index > 50 ifTrue:[ break value ]. ]

 to: stop by: incr doWithExit: aBlock

For each element of the interval from the receiver up to the argument stop, incrementing
by step, evaluate aBlock passing the element as argument.
Pass a break argument, to allow for premature exit of the loop.
Returns nil or the value passed to the exit>>value: message.

Notice, that this is different to a return statement in the block,
which returns from the enclosed method, NOT only from the block.

Usage example(s):

1 to:100 by:5 doWithExit:[:index :exit | Transcript showCR:index printString. index > 50 ifTrue:[ exit value:nil ]. ]

 to: stop count: aBlock

same as (self to:stop) count:aBlock

Usage example(s):

1 to:10 count:[:n | n even]

 to: stop do: aBlock

For each element of the interval from the receiver up to the argument stop,
evaluate aBlock, passing the number as argument.

Usage example(s):

1 to:10 do:[:i | Transcript showCR:i]. 1 to:10 by:2 do:[:i | Transcript showCR:i]. 10 to:1 by:-1 do:[:i | Transcript showCR:i].

 to: stop do: aBlock separatedBy: actionBetween

For each element of the interval from the receiver up to the argument stop,
evaluate aBlock, passing the number as argument.
Between each, evaluate actionBetween (but not before the first and not after the last)

Usage example(s):

1 to:10 do:[:i | Transcript show:i] separatedBy:[ Transcript show:', '].

 to: stop doWithBreak: aBlock

For each element of the interval from the receiver up to the argument stop,
evaluate aBlock, passing the number as argument.
Pass a break argument, to allow for premature exit of the loop.
Same as to:doWithExit: for compatibility

Usage example(s):

1 to:10 doWithBreak:[:index :break | Transcript showCR:index printString. index > 5 ifTrue:[ break value ]. ]

 to: stop doWithExit: aBlock

For each element of the interval from the receiver up to the argument stop,
evaluate aBlock, passing the number as optional argument.
Passes an additional exit object, which can be used to leave
the loop early, by sending it a #value: or #value message.
Returns nil or the value passed to the exit>>value: message.

Notice, that this is different to a return statement in the block,
which returns from the enclosed method, NOT only from the block.

Usage example(s):

1 to:10 doWithExit:[:index :exit | index == 5 ifTrue:[ exit value:nil ]. Transcript showCR:index. ]. 1 to:10 doWithExit:[:index :exit | index == 5 ifTrue:[ exit value ]. Transcript showCR:index. ].

 printWithoutFractionIfPossibleOn: aStream

append a printed representation of the receiver to
the argument, aStream.
If the receiver has no fractional part (i.e. ends with .0),
then print the integer part only.
The fallback here just prints, assuming that this is not possible.

 between: min and: max

return true if the receiver is greater than or equal to the argument min
and less than or equal to the argument max

Usage example(s):

1.2 between:1 and:2 (3/2) between:1 and:2 (3/2) between:0 and:1

 in: anInterval

return whether the receiver is within the interval bounds

Usage example(s):

1.2 in:(1 to: 2) (3/2) in:(1 to: 2) (3/2) in:(0 to: 1)